#charset "us-ascii"

/* 
 *   Copyright (c) 2000, 2006 Michael J. Roberts.  All Rights Reserved.
 *   
 *   This module defines a number of low-level functions and classes that
 *   most TADS 3 programs will need, whether based on the adv3 library or
 *   not.  This module includes the main program entrypoint, the basic
 *   Exception classes, and the modular initialization framework.
 *   
 *   The compiler automatically links this module into every program by
 *   default, but you can override this by specifying the "-nodef" option
 *   to t3make.  If you remove this module, you'll have to provide your own
 *   implementations for many of the functions and classes defined here.  
 */

#include "tads.h"
#include "reflect.h"
#include "strbuf.h"


/* ------------------------------------------------------------------------ */
/*
 *   Main program entrypoint.  The VM invokes this function at program
 *   startup.  
 */
_main(args)
{
    /* call the common main entrypoint, with no startup file specified */
    _mainCommon(args, nil);
}

/* declare 'main' as a function, in case it's not otherwise defined */
extern function main;

/*
 *   Main program entrypoint for restoring a saved state.  The VM invokes
 *   this function at startup instead of _main() when the user explicitly
 *   specifies a saved state file to restore when starting the program.
 *   (On a command-line interpreter, this would involve using a special
 *   option on the T3 interpreter command line; for a GUI shell, this
 *   might simply involve double-clicking on the desktop icon for a saved
 *   state file.)
 *   
 *   Note that we must export this as the 'mainRestore' symbol so that the
 *   interpreter knows how to find it.  
 */
export _mainRestore 'mainRestore';
_mainRestore(args, restoreFile)
{
    /* call the common main entrypoint */
    _mainCommon(args, restoreFile);
}

/*
 *   Common main entrypoint.  This function can be called with or without
 *   a saved state file to restore.  
 */
_mainCommon(args, restoreFile)
{    
    try
    {
        /* 
         *   Keep going as long as we keep restarting.  Note that the
         *   restoreFile only counts on the first iteration, so we clear it
         *   out after each iteration; if we RESTART after that, we'll want
         *   to just start the game from the beginning.  
         */
        for ( ; ; restoreFile = nil)
        {
            /* perform load-time initialization */
            initAfterLoad();

            /* if we're in preinit-only mode, we're done */
            if (t3GetVMPreinitMode())
                return;

            /* catch any RESTART signals thrown out of the main entrypoint */
            try
            {
                /* 
                 *   If there's a saved state file to restore, call our
                 *   mainRestore() function instead of main().  If
                 *   mainRestore() isn't defined, show a message to this
                 *   effect but keep going.  
                 */
                if (restoreFile != nil
                    && dataType(mainGlobal.mainRestoreFunc) == TypeFuncPtr)
                {
                    /* 
                     *   Call the user's main startup-and-restore
                     *   entrypoint function.  Note that we call indirectly
                     *   through our function pointer so that we don't
                     *   force a function called mainRestore() to be linked
                     *   with the program.  
                     */
                    (mainGlobal.mainRestoreFunc)(args, restoreFile);
                }
                else
                {
                    /* 
                     *   if we have a restore file but no mainRestore
                     *   routine, explain to the user that they'll have to
                     *   restore manually 
                     */
                    if (restoreFile != nil)
                    {
                        "\n[This program cannot restore the saved position
                        file automatically.  Please try restoring the
                        saved position file again using a command within
                        the program.]\b";
                    }

                    /* call the selected main entrypoint */
                    flexcall(&main, args);
                }

                /* 
                 *   we made it through the main entrypoint without a
                 *   restart, so we're done 
                 */
                break;
            }
            catch (RestartSignal rsig)
            {
                /* 
                 *   call the intrinsic restartGame function to reset all
                 *   of the static objects to their initial state 
                 */
                restartGame();

                /* 
                 *   Now that we've reset the VM, update the restart ID in
                 *   the main globals.  Note that we waited until now to do
                 *   this, because this change would have been lost in the
                 *   reset if we'd made the change before the reset.  Note
                 *   also that the 'rsig' object itself will survive the
                 *   reset because the thrower presumably allocated it
                 *   dynamically, hence it's not a static object subject to
                 *   reset.  
                 */
                mainGlobal.restartID = rsig.restartID;

                /*
                 *   Now we can just continue on to the next iteration of
                 *   the restart loop.  This will take us back to the
                 *   initialization and enter the game as though we'd just
                 *   started the program again.  
                 */
            }
        }
    }
    catch (ProgramException exc)
    {
        /* 
         *   just re-throw these out to the VM, so that the VM exits to
         *   the operating system with an error indication 
         */
        throw exc;
    }
    catch (Exception exc)
    {
        /* write output to the main console */
        t3SetSay(_default_display_fn);
        
        /* display the unhandled exception */
        "\n<<exc.displayException()>>\n";
    }
    finally
    {
        /* before exiting, call registered exit handlers */
        mainAtExit.callHandlers();
    }
}

/* ------------------------------------------------------------------------ */
/*
 *   Flexible function call.  This calls the given function, passing as
 *   many arguments from the given argument list as the function actually
 *   wants.  If the list doesn't have enough arguments to satisfy the
 *   function's minimum requirements, we add 'nil' arguments to pad out the
 *   minimum.  If the list exceeds the function's maximum, we drop
 *   arguments past the maximum.
 */
flexcall(func, [args])
{
    /* get the function's desired argument list */
    local paramDesc = getFuncParams(func);

    /* add or remove arguments as needed to fit the limits */
    local n = args.length();
    if (n < paramDesc[1])
    {
        /* we need more to satisfy the minimum - add nil values */
        args += makeList(nil, paramDesc[1] - n);
    }
    else if (n > paramDesc[1] + paramDesc[2] && !paramDesc[3])
    {
        /* 
         *   the function doesn't take infinite arguments, and we have more
         *   than it allows in the fixed plus optional parts, so drop the
         *   extra elements 
         */
        args = args.sublist(1, paramDesc[1] + paramDesc[2]);
    }

    /* call the function */
    func(args...);
}

/* ------------------------------------------------------------------------ */
/*
 *   Restart signal.  This can be used to restart from the main
 *   entrypoint.  The caller should create one of these objects, then use
 *   restartGame() (or an equivalent from a different function set, if
 *   appropriate) to reset static object state to the initial program load
 *   conditions, then throw the signal object.  
 */
class RestartSignal: Exception
    construct()
    {
        /* 
         *   use the next restart ID, so we can tell that we're on a fresh
         *   run on this session 
         */
        restartID = mainGlobal.restartID + 1;
    }
;

/* ------------------------------------------------------------------------ */
/*
 *   General post-load initialization.  The main program entrypoint
 *   _main() calls this routine to set up the default display function,
 *   run pre-initialization if necessary, and run initialization.  This
 *   routine is also useful for the target of a restartGame() routine, to
 *   perform all of the basic load-time initialization again after a
 *   restart.  
 */
initAfterLoad()
{
    /* establish the default display function */
    t3SetSay(_default_display_fn);

    /* if we haven't run preinit, do so now */
    if (!mainGlobal.preinited_)
    {
        /* 
         *   Explicitly run garbage collection prior to preinit.
         *   
         *   In most cases, this is unnecessary, but in some cases it's
         *   important.  In particular, object loops (over all objects, or
         *   over all instances of a given class) can still see otherwise
         *   unreachable objects.  It's common to do object loops in
         *   preinit to set up static data caches and tables and so on.  If
         *   there *were* any garbage objects lying around, preinit could
         *   find them via object loops, and might register them into
         *   tables or what not.
         *   
         *   Even considering the preinit object loop, doing a garbage
         *   collection sweep would *still* be redundant in most cases,
         *   since preinit is normally done right after compilation, when
         *   the program wouldn't yet have had a chance to create any
         *   garbage objects to be worried about in object loops.  However,
         *   there's still one more case to consider, and that's RESTART:
         *   in a debug build, or even in some release builds, we'd have to
         *   re-run preinit after a RESTART, and there certainly could be
         *   garbage objects left around from before the RESTART.
         *   
         *   To ensure that we deal gracefully with this combination of
         *   conditions - garbage objects, RESTART, and object loops in
         *   preinit - simply do an explicit garbage collection run before
         *   invoking preinit.  
         */
        t3RunGC();

        /* run our internal preinit */
        _preinit();
        
        /* remember that we've run preinit */
        mainGlobal.preinited_ = true;
    }

    /* if we're not in preinit-only mode, run internal initialization */
    if (!t3GetVMPreinitMode())
        _init();
}



/* ------------------------------------------------------------------------ */
/*
 *   Module Execution Object.  This is an abstract base class for various
 *   classes that provide modular execution hooks.  This class and its
 *   subclasses are mix-in classes - they can be multiply inherited by any
 *   object (as long as it's not already some other kind of module
 *   execution object).
 *   
 *   The point of the Module Execution Object and its subclasses is to
 *   allow libraries and user code to define execution hooks, without
 *   having to worry about what other libraries and user code bits are
 *   defining the same hook.  When we need to execute a hook defined via
 *   this object, we iterate over all of the instances of the appropriate
 *   subclass and invoke its execute() method.
 *   
 *   By default, the order of execution is arbitrary.  In some cases,
 *   though, dependencies will exist, so that one object cannot be invoked
 *   until another object has already been invoked.  In these cases, you
 *   must set the execBeforeMe property to contain a list of the objects
 *   whose execute() methods must be invoked before this object's
 *   execute() method is invoked.  The library will check this list before
 *   calling execute() on this object, and ensure that each object in the
 *   list has been invoked before calling this object's execute().  
 */
class ModuleExecObject: object
    /* 
     *   List of objects that must be executed before me - by default, the
     *   order doesn't matter, so we'll set this to an empty list.
     *   Instances can override this if it is necessary to execute other
     *   objects before this object can be executed.  
     */
    execBeforeMe = []

    /*
     *   List of objects that must be executed after me - this is
     *   analogous to execBeforeMe, but we make sure we run before these. 
     */
    execAfterMe = []

    /* 
     *   Subclass-specific execution method.  Each subclass should
     *   override this method to provide its execution code.  
     */
    execute() { }


    /* 
     *   PRIVATE METHODS AND PROPERTIES.  Subclasses and instances should
     *   not need to override or invoke these.  
     */

    /* flag - true if we've been executed on this round */
    isExecuted_ = nil

    /* flag - true if we're in the process of executing */
    isDoingExec_ = nil

    /* execute - internal method: checks dependency order */
    _execute()
    {
        /*
         *   If I've already been executed, there's nothing more that I
         *   need to do.  We might be called by the arbitrarily-ordered
         *   iteration over all objects after we've already been executed,
         *   because we might be executed explicitly by an object that
         *   depends upon us if it's reached before we are.  
         */
        if (isExecuted_)
            return;

        /* 
         *   If we're in the process of executing any of the objects we
         *   depend upon, and a dependent calls us, we have a circular
         *   dependency.  
         */
        if (isDoingExec_)
            throw new CircularExecException(self);

        /*
         *   Mark ourselves as being in the process of executing.  If
         *   there are any circular dependencies (i.e., if we depend on an
         *   object, which in turn depends on us), it's clearly an error,
         *   in that both objects can't be executed before the other.
         *   This flag allows us to detect circular dependencies by
         *   noticing if we're called by a dependent while we're in the
         *   process of calling the things we depend upon.  
         */
        isDoingExec_ = true;
        
        /*
         *   Check each entry in my 'before' list to ensure that they've
         *   all been executed already.  Invoke execute() now for any that
         *   haven't.  
         */
        for (local i = 1, local cnt = execBeforeMe.length() ;
             i <= cnt ; ++i)
        {
            local cur;

            /* get this object */
            cur = execBeforeMe[i];
            
            /* if this one hasn't been executed yet, do so now */
            if (!cur.isExecuted_)
            {
                /* 
                 *   This one hasn't been executed yet - explicitly
                 *   execute it now.  Note that we do this recursively
                 *   through the internal execution method, so that 'cur'
                 *   has a chance to execute any objects that it depends
                 *   upon.  
                 */
                cur._execute();
            }
        }

        /* 
         *   we've resolved all of our dependencies, so we're good to go -
         *   run the user's execution code 
         */
        execute();

        /* 
         *   mark ourselves as having been executed, so we don't run the
         *   user's code again should we be called again by a dependent or
         *   by the global iteration loop later in the scan 
         */
        isExecuted_ = true;
        isDoingExec_ = nil;
    }

    /* flag to indicate that this is the first time running classExec */
    hasInitialized_ = nil

    /*
     *   Class execution.  Call this method on the particular class of
     *   modules to execute.  We'll iterate over all instances of that
     *   class and invoke each instance's _execute() method. 
     */
    classExec()
    {
        /*
         *   If this is the first time running this classExec, turn
         *   execAfterMe dependencies into appropriate execBeforeMe
         *   dependencies.  
         */
        if (!hasInitialized_)
        {
            /* 
             *   Go through all instances of this type of initializer, and
             *   re-cast the execAfterMe lists as execBeforeMe lists.  
             */
            forEachInstance(self,
                function(obj)
                {
                    foreach(local dependent in obj.execAfterMe)
                        dependent.execBeforeMe += obj;
                });

            /* remember that we're now initialized */
            hasInitialized_ = true;
        }
        
        /* 
         *   since we're starting a new round, clear all of the 'executed'
         *   flags in all of the objects, to ensure that we execute all
         *   objects on this round (this cleans up the flag settings from
         *   any previous rounds) 
         */
        forEachInstance(self,
            { obj: obj.isExecuted_ = obj.isDoingExec_ = nil });

        /* execute all objects */
        forEachInstance(self, { obj: obj._execute() });
    }
;

/*
 *   Pre-Initialization object.  During pre-initialization, we'll invoke
 *   the execute() method on each instance of this class.  
 */
class PreinitObject: ModuleExecObject
    /*
     *   Each instance of this object MUST override execute() with the
     *   specific pre-initialization code that the instance wants to
     *   perform.
     *   
     *   In addition, each instance can optionally set the property
     *   execBeforeMe to a list of the other PreinitObject's that must be
     *   invoked before this object is.  If this property is not set, this
     *   object's place in the preinit execution order will be arbitrary.  
     */
;

/*
 *   Initialization object.  During initialization, just before calling
 *   the user's main(args) function, we'll invoke the execute() method on
 *   each instance of this class. 
 */
class InitObject: ModuleExecObject
    /*
     *   Each instance of this object MUST override execute() with the
     *   specific initialization code that the instance wants to perform.
     *   
     *   In addition, each instance can optionally set the property
     *   execBeforeMe to a list of the other InitObject's that must be
     *   invoked before this object is.  If this property is not set, this
     *   object's place in the initialization execution order will be
     *   arbitrary.  
     */
;


/*
 *   Exception: circular execution dependency in ModuleExecObject
 */
class CircularExecException: Exception
    construct(obj) { obj_ = obj; }
    displayException()
    {
        "circular module dependency detected (refer to
        ModuleExecObject._execute() in _main.t)";
    }

    /* 
     *   The object that detected the circular dependency.  We can't use
     *   this for much ourselves, but it might be useful to store this
     *   information so that it's available to the programmer from within
     *   the debugger.  
     */
    obj_ = nil
;

/*
 *   Library pre-initialization.  This is called immediately after
 *   compilation to pre-initialize the program.  Any changes made here to
 *   object states become part of the initial state stored in the image
 *   file, so this establishes the static initial state of the program.
 *   
 *   The advantage of doing work during pre-initialization is that this
 *   work is done once, during compilation, and is thus not repeated each
 *   time a user starts the program.  Time-consuming initialization work
 *   can thus be made invisible to the user.
 *   
 *   Note that the pre-initialization code should never do anything that
 *   involves the user interface, since this code runs during compilation
 *   and does not run again when users start the program.  So, anything
 *   that you want a user to see must be done during normal initialization
 *   (such as in the main() routine), not here.  
 */
_preinit()
{
    local symtab;

    /* try getting the mainRestore() function from the global symbol table */
    if ((symtab = t3GetGlobalSymbols()) != nil)
        mainGlobal.mainRestoreFunc = symtab['mainRestore'];

    /* execute all preinit objects */
    PreinitObject.classExec();
}

/*
 *   Library initialization.  This is called during each program start-up
 *   to initialize the program.  Since this is run each time the user
 *   starts the program, this can display any introductory messages, set
 *   up the user interface, and so on.  
 */
_init()
{
    /* execute all init objects */
    InitObject.classExec();
}

/* ------------------------------------------------------------------------ */
/*
 *   For convenience, a simple object iterator function.  This function
 *   invokes a callback function for each instance of the given class, in
 *   arbitrary order.
 *   
 *   The callback is invoked with one argument, which gives the current
 *   instance.  The callback can "break" out of the loop by throwing a
 *   BreakLoopSignal, which can be done conveniently using the breakLoop
 *   macro.  
 */
forEachInstance(cls, func)
{
    try
    {
        /* loop over all objects of the given class */
        for (local obj = firstObj(cls) ; obj != nil ; obj = nextObj(obj, cls))
            func(obj);
    }
    catch (BreakLoopSignal sig)
    {
        /* 
         *   ignore the signal - it simply means we want to terminate the
         *   loop and return to the caller 
         */
    }
}

/*
 *   Find an instance of the given class for which the given function
 *   returns true.  We iterate over objects of the given class in
 *   arbitrary order, and return the first instance for which the function
 *   returns true.  Retursn nil if there is no such instance.  
 */
instanceWhich(cls, func)
{
    /* loop over all objects of the given class */
    for (local obj = firstObj(cls) ; obj != nil ; obj = nextObj(obj, cls))
    {
        /* if the callback returns true for this object, return the object */
        if (func(obj))
            return obj;
    }

    /* 
     *   we didn't find any instances for which the callback returns true;
     *   indicate this by returning nil 
     */
    return nil;
}

/*
 *   An exception object for breaking out of a callback loop, such as
 *   forEachInstance. 
 */
class BreakLoopSignal: Exception
    displayException() { "loop break signal"; }
;


/* ------------------------------------------------------------------------ */
/*
 *   Get the "translated" datatype of a value.  This is essentially the
 *   same as dataType(), except that anonymous function objects and dynamic
 *   function objects are treated as being "function pointer" types
 *   (TypeFuncPtr).  
 */
dataTypeXlat(val)
{
    local t;

    /* get the base type */
    t = dataType(val);
    
    /* if it's an anonymous function, return TypeFuncPtr */
    if (t == TypeObject
        && (val.ofKind(AnonFuncPtr)
            || (defined(DynamicFunc) && val.ofKind(DynamicFunc))))
        return TypeFuncPtr;

    /* otherwise, just return the base type */
    return t;
}

/* ------------------------------------------------------------------------ */
/*
 *   Base class for all exception objects.  We derive all exceptions from
 *   this base class so that we can write 'catch' blocks that catch all
 *   exceptions by catching 'Exception'.
 *   
 *   The displayException() method displays a message describing the
 *   exception.  Subclasses should override this method.  
 */
class Exception: object
    /* construct, with an optional message describing the error */
    construct(msg?, ...)
    {
        /* if there's a message, save it, otherwise keep the default */
        if (msg != nil)
            errmsg_ = msg;
    }

    /* display the exception - should always be overridden */
    displayException()
    {
        "<<errmsg_>>";
    }

    /* 
     *   Get the exception message as a string.  This captures the output
     *   of displayException() and returns it a string.  Use this instead
     *   of accessing errmsg_, since that member is private and might not
     *   reflect the actual displayed message. 
     */
    getExceptionMessage()
    {
        /* capture and return the displayed exception message as a string */
        return _outputCapture({: displayException() });
    }

    /* 
     *   Private member: The error message passed to the constructor, if
     *   any.  Note that this doesn't necessarily contain the actual
     *   displayed exception message, since displayException() can be
     *   overridden in subclasses to display additional parameters or other
     *   text entirely.  The definitive message is the one that
     *   displayException() generates.  If you want the displayed message
     *   as a string, use getExceptionMessage().  
     */
    errmsg_ = 'Unknown exception'

    /* 
     *   Display a stack trace, given a list of T3StackInfo objects.  Note
     *   that, for efficiency, we do not by default cache a stack trace
     *   when an exception occurs; individual subclasses can obtain a
     *   stack trace if desired at construction and use the information to
     *   show a stack trace for the exception. 
     */
    showStackTrace(stackList)
    {
        local haveSrc;

        /* check to see if there's any source info in the stack trace */
        haveSrc = nil;
        foreach (local cur in stackList)
        {
            /* note if we have source info here */
            if (cur.srcInfo_ != nil)
            {
                /* 
                 *   we have source information - note it and stop
                 *   searching, since even one bit of source info is
                 *   enough to show the stack 
                 */
                haveSrc = true;
                break;
            }
        }

        /* 
         *   if we have any source information at all, or we have
         *   reflection services available to decode the stack trace
         *   symbolically, show the stack 
         */
        if (haveSrc || mainGlobal.reflectionObj != nil)
        {
            for (local i = 1, local cnt = stackList.length() ; i <= cnt ; ++i)
            {
                local cur = stackList[i];
                
                /* show a mark next to level 1, spaces elsewhere */
                if (i == 1)
                    "--&gt;";
                else
                    "\ \ \ ";

                /* 
                 *   if there's a system reflection object, show symbolic
                 *   information on the current function call; otherwise,
                 *   simply show the source location 
                 */
                if (mainGlobal.reflectionObj != nil)
                {
                    /* reflection is available - show full symbolic info */
                    "<<mainGlobal.reflectionObj.
                      formatStackFrame(cur, true)>>";
                }
                else
                {
                    /* no reflection information - show source only */
                    if (cur.srcInfo_ != nil)
                        "<<cur.srcInfo_[1]>>, line <<cur.srcInfo_[2]>>";
                    else if (cur.isSystem())
                        "&lt;System&gt;";
                    else
                        "???";
                }

                /* end the line */
                "\n";
            }
        }
    }
;


/* ------------------------------------------------------------------------ */
/*
 *   RuntimeError exception class.  The VM creates and throws an instance
 *   of this class when any run-time error occurs.  The VM explicitly sets
 *   the exceptionMessage property to a string giving the VM error message
 *   for the run-time error that occurred.  
 */
class RuntimeError: Exception
    construct(errno, ...)
    {
        /* remember the VM error number */
        errno_ = errno;

        /* 
         *   Store a stack trace for the current location.  Always discard
         *   the first element of the result, since this will reflect
         *   RuntimeError.construct, which is obviously not interesting.  
         */
        stack_ = t3GetStackTrace().sublist(2);

        /* 
         *   The next element of the stack trace is usually a native code
         *   frame, because the VM itself invokes our constructor in
         *   response to a runtime exception; this is not an interesting
         *   frame, so if it's present, remove it.  
         */
        if (stack_.length() > 0 && stack_[1].isSystem())
            stack_ = stack_.sublist(2);
    }

    /* create a runtime error with a given error message */
    newRuntimeError(errno, msg)
    {
        local e = new RuntimeError(errno);
        e.exceptionMessage = msg;
        return e;
    }

    /* display the exception */
    displayException()
    {
        /* show the exception message */
        "Runtime error: <<exceptionMessage>>\n";

        /* show a stack trace if possible */
        showStackTrace(stack_);
    }

    /* check to see if it's a debugger signal of some kind */
    isDebuggerSignal()
    {
        return errno_ is in (
            2391,                        /* debugger 'abort command' signal */
            2392                               /* debugger 'restart' signal */
        );
    }

    /* the VM error number of the exception */
    errno_ = 0

    /* the exception message, provided to us by the VM after creation */
    exceptionMessage = ''

    /* the stack trace, which we store at the time we're created */
    stack_ = nil
;

/*
 *   Export our RuntimeError class so that the VM knows about it and can
 *   create instances of it.  Also export our exceptionMessage property,
 *   so the VM can store its explanatory text there.
 */
export RuntimeError;
export exceptionMessage;

/*
 *   Unknown character set exception - this is thrown from any routine that
 *   needs a local character set mapping when no mapping exists on the local
 *   platform. 
 */
class UnknownCharSetException: Exception
    displayException = "Unknown character set"
;

/* 
 *   this exception object must be exported for use by the CharacterSet
 *   intrinsic class 
 */
export UnknownCharSetException 'CharacterSet.UnknownCharSetException';


/*
 *   A Program Exception terminates the entire program, passing an error
 *   indication to the operating system.  The VM doesn't provide a way to
 *   specify the *particular* error code to return to the OS, as there's no
 *   portable set of error codes; rather, the VM simply returns a code to
 *   the OS that means generically that an error occurred, if there's any
 *   such concept on the local operating system.  The VM will normally
 *   display this message just before it terminates the program, possibly
 *   with some additional text mentioning that a program error occurred
 *   (such as "unhandled exception: <your message>").
 */
class ProgramException: Exception
    construct(msg) { exceptionMessage = msg.htmlify(); }
    displayException() { "<<exceptionMessage>> "; }
;

/*
 *   A StorageServerError is thrown when a file operation on a remote
 *   storage server fails.  The storage server is used when the game runs
 *   on a Web game server in client/server mode.  In Web mode, files are
 *   stored on a separate storage server rather than on the Web server
 *   itself, so that the files can be transparently accessed if the game is
 *   continued from another Web server.  This exception is used when a
 *   request to the storage server fails, which could be due to an error on
 *   the storage server, a network error communicating between the game
 *   server and the storage server, or an invalid request (e.g., incorrect
 *   user credentials).  
 */
class StorageServerError: RuntimeError
    construct(errno, msg)
    {
        /* 
         *   Do the base class construction.  Note that errno is the
         *   VM-level error number, which is usually just the generic
         *   "storage server error" code.  The storage server provides a
         *   separate, more specific error code of its own as the first
         *   token of the message string.  
         */
        inherited(errno);
        
        /* 
         *   storage server error messages are formatted with an error code
         *   as the first space-delimited token, and a human-readable
         *   message following 
         */
        local sp = msg.find(' ');
        errCode = msg.substr(1, sp - 1);
        msg = msg.substr(sp + 1);

        /* 
         *   If the error code is a negative integer, it's an error on the
         *   client side sending the HTTP request to the storage server.
         *   If it's a positive integer, it's an HTTP error code from the
         *   storage server.  Otherwise it's an error abbreviation token
         *   from the server. 
         */
        local errNum = toInteger(errCode);
        if (errNum < 0)
        {
            local reqErrs = [
                -1 -> 'out of memory',
                -2 -> 'unable to connect',
                -3 -> 'network error',
                -4 -> 'invalid parameters',
                -5 -> 'error reading temporary file',
                -6 -> 'error writing temporary file',
                * -> 'error code <<errNum>>'
            ];
            errMsg = reqErrs[errNum];
        }
        else if (errNum > 0)
            errMsg = 'HTTP error (status code <<errCode>>)';
        else
            errMsg = msg;
    }

    /* the storage server error code */
    errCode = nil

    /* 
     *   error message - this is the message text we get back from the
     *   storage server for a request that's successful at the HTTP level
     *   but fails on the storage server, OR a message describing the HTTP
     *   error or network error that caused the request to fail 
     */
    errMsg = 'no details available'

    /* display the exception */
    displayException()
    {
        /* show the exception message */
        "Storage server error: <<errMsg>>\n";

        /* show a stack trace if possible */
        showStackTrace(stack_);
    }
;

/* export this for use by the interpreter networking package */
export StorageServerError 'StorageServerError';


/* ------------------------------------------------------------------------ */
/*
 *   Default string display function.  Our main entrypoint code
 *   establishes this function as the default output function.  
 */
_default_display_fn(str) { _tads_io_say(str); }

/*
 *   Raw output capture.  This bypasses any filtering and directly captures
 *   any output generated by the callback. 
 */
_outputCapture(func)
{
    /* temporarily set the low-level string output to capture output */
    local buf = new StringBuffer();
    local oldSay = t3SetSay({str: buf.append(str)});

    /* make sure we restore the "say" function on the way out */
    try
    {
        /* call the callback in the new capture context */
        func();

        /* return the captured data */
        return toString(buf);
    }
    finally
    {
        /* restore the old "say" function */
        t3SetSay(oldSay);
    }
}


/* ------------------------------------------------------------------------ */
/*
 *   The stack information object.  The intrinsic function
 *   t3GetStackTrace() in the 't3vm' function set returns a list of these
 *   objects; each object represents a level in the stack trace.  
 */
class T3StackInfo: object
    /*
     *   Construct a stack level object.  The system invokes this
     *   constructor with information on the stack level.
     */
    construct(func, obj, prop, selfObj, argList, srcInfo,
              locals, namedArgs, frameDesc)
    {
        /* remember the values */
        func_ = func;
        obj_ = obj;
        prop_ = prop;
        self_ = selfObj;
        argList_ = argList;
        srcInfo_ = srcInfo;
        locals_ = locals;
        namedArgs_ = namedArgs;
        frameDesc_ = frameDesc;
    }

    /*
     *   Is this a system routine?  This returns true if an intrinsic
     *   function or an intrinsic class method is running at this level. 
     */
    isSystem()
    {
        /*
         *   It's a system function if:
         *   
         *   - we have NEITHER a function nor a method
         *.  - the function is a built-in function pointer
         *.  - the defining object is an intrinsic class
         *   
         *   The first case applies to pre-3.0.19 VMs, where no information
         *   was available for native callers.  Starting in 3.0.19, full
         *   information is available.  
         */
        return ((func_ == nil && obj_ == nil)
                || dataType(func_) == TypeBifPtr
                || (obj_ != nil && IntrinsicClass.isIntrinsicClass(obj_)));
    }

    /* 
     *   the function running at this stack level - this is nil if an
     *   object property is running instead of a function 
     */
    func_ = nil

    /* 
     *   The object and property running at this stack level - these are
     *   nil if a function is running instead of an object method.  The
     *   object is the object where the method is actually defined - this
     *   might not be the same as self, because the object might have
     *   inherited the method from a base class.  
     */
    obj_ = nil
    prop_ = nil

    /* 
     *   the 'self' object at this level - this is nil if a function is
     *   running at this level instead of an object method 
     */
    self_ = nil

    /* 
     *   The list of positional arguments to the function or method.  Each
     *   element is the value of an argument; the list is arranged in the
     *   same order as the arguments. 
     */
    argList_ = []

    /*
     *   Local variables.  This is a LookupTable containing the local
     *   variables currently in scope at this stack level.  Each element in
     *   the table has a string key (index) giving the name of the local
     *   variable, and each corresponding value is the local's current
     *   value.  The table is only included when the stack listing was
     *   produced by a call to t3GetStackTrace() with the T3GetStackLocals
     *   flag set; otherwise it's nil.  If the locals were requested, and
     *   the stack level has no local variables, this will be an empty
     *   lookup table.  
     */
    locals_ = nil

    /*
     *   Named arguments.  This is a LookupTable containing the named
     *   arguments passed in from this stack level.  Each element in the
     *   table has a string key (index) giving the name of the argument,
     *   and each corresponding value is the value of that argument.  If
     *   there are no named arguments, this value is nil.  
     */
    namedArgs_ = nil

    /*
     *   The source location of the next code to be executed in the
     *   function or method in this frame.  If source-level debugging
     *   information is available for the current execution point in this
     *   frame, this will contain a list of two values:
     *   
     *   srcInfo_[1] = string giving the name of the source file
     *.  srcInfo_[2] = integer giving the line number in the source file
     *   
     *   If the program wasn't compiled with source-level debugging
     *   information, or the current code location in the frame doesn't
     *   have any source information, this will be set to nil.
     *   
     *   Note that the location reflected here is the *return address* in
     *   this frame - that is, the code location that will be executed when
     *   control returns to the frame.  This means that the source location
     *   will frequently appear as the next executable line after the one
     *   that called the next inner frame, because this is where execution
     *   will resume when control returns to the frame.  
     */
    srcInfo_ = nil

    /*
     *   A StackFrameDesc object that can be used to get information from
     *   the frame and change local variables in the frame.  
     */
    frameDesc_ = nil
;

/* export T3StackInfo for use by the system */
export T3StackInfo;


/* ------------------------------------------------------------------------ */
/*
 *   Stream state object for String.specialsToHtml().
 */
class SpecialsToHtmlState: object
    /* 
     *   Reset the state.  This should be used when the output stream
     *   context is reset, such as when clearing the window.  
     */
    resetState()
    {
        flags_ = 0;
        tag_ = '';
    }

    /* 
     *   Explicitly reset to the start of a line.  This can be called after
     *   a non-output operation that resets the line position, such as
     *   reading an input line.  
     */
    resetLine()
    {
        /* reset the in-line flag, space flag, qspace flag, and tab column */
        flags_ &= ~(0x0001 | 0x0040 | 0x0080 | 0x0300);
    }

    /* 
     *   Internal output state flags at end of last string parsed.  This is
     *   a combination of bit flags:
     *   
     *   0x0001 - last string ended within a line of text
     *.  0x0002 - caps flag '\^' pending
     *.  0x0004 - lowercase flag '\v' pending
     *.  0x0008 - last string ended within an HTML tag
     *.  0x0010 - last string ended in double-quoted HTML tag attribute text
     *.  0x0020 - last string ended in single-quoted HTML tag attribute text
     *.  0x0040 - last string ended with an ordinary space
     *.  0x0080 - last string ended with a quoted space '\ '
     *.  0x0100 - <Q> parity level: 0=double quotes, 1=single quotes
     *.  0x0300 - distance from last '\t' tab column (0..3)
     */
    flags_ = 0

    /* tag in progress at end of last string parsed */
    tag_ = ''
;
    


/* ------------------------------------------------------------------------ */
/*
 *   global data object for this module
 */
mainGlobal: object
    /* flag: we've run pre-initialization */
    preinited_ = nil

    /* 
     *   The global reflection object - if the program is compiled with
     *   the standard reflection module, that module will set this
     *   property to point to the reflection object.
     *   
     *   We use this so that we don't require the reflection module to be
     *   included.  If the module isn't included, this will be nil, so
     *   we'll know not to use reflection.  If this is not nil, we'll know
     *   we can use reflection services.  
     */
    reflectionObj = nil

    /*
     *   Restart ID.  This is an integer that indicates how the main
     *   entrypoint was last reached.  This is initially zero; each time
     *   we restart the game, this is incremented.
     *   
     *   The restart ID is the only information that survives across a
     *   restart boundary.  Other than this, entering via a restart is
     *   exactly like loading the program from scratch; all other
     *   information about the program state before the restart is lost in
     *   the restart operation.  
     */
    restartID = 0

    /* pointer to mainRestore function, if defined */
    mainRestoreFunc = nil
;

/* ------------------------------------------------------------------------ */
/*
 *   At-exit handlers.  This is a registry for custom handlers that are to
 *   be invoked just before the program terminates.  
 */
transient mainAtExit: object
    /*
     *   Add an at-exit handler.  User code can call this to register a
     *   handler that will be invoked just before the program exits. 
     */
    addHandler(func)
    {
        handlers.append(func);
    }

    /* call our exit handlers */
    callHandlers()
    {
        /* call each handler in the list */
        foreach (local f in handlers)
        {
            try
            {
                /* call this handler */
                f();
            }
            catch (Exception exc)
            {
                /* display and ignore any exceptions it throws */
                "\nError in exit handler: <<exc.displayException()>>\n";
            }
        }
    }

    /* list of exit handlers */
    handlers = static new Vector()
;

/* ------------------------------------------------------------------------ */
/*
 *   <<one of>> index generator.  The compiler generates an anonymous
 *   instance of this class for each <<one of>> list in string, setting the
 *   property 'numItems' to the number of items in the list, and
 *   'listAttrs' property to a string giving the sequence type.  The
 *   compiler generates a call to getNextIndex() within the string to get
 *   the next index value, which is an integer from 1 to numItems.  
 */
class OneOfIndexGen: object
    /* number of list items */
    numItems = 1

    /* 
     *   List attributes.  This is a string with a comma-delimited list of
     *   tokens describing the treatment on the list for each fetch.  The
     *   first call to getNextIndex() takes the first token off the list
     *   and generates an appropriate return value, possibly queuing up a
     *   list of future values.  The next call to getNextIndex() reads from
     *   the queue.  Once the queue is exhausted, the next call takes the
     *   second token off the attribute list and repeats the process.  Once
     *   the attribute list is down to one token, we don't remove the
     *   token, but simply repeat it forever.
     *   
     *   For example, 'seq,rand' runs through the entire list in sequence
     *   once, then generates independently random values from then on.
     *   'shuffle,stop' runs through the list once in shuffled order, then
     *   repeats the last pick from the shuffled list forever.
     *   
     *   The individual attribute values are:
     *   
     *   rand - pick an item at random, independently of past selections.
     *   
     *   rand-norpt - pick an item at random, but don't pick the single
     *   most recent item chosen, to avoid repeating the same thing twice
     *   in a row.
     *   
     *   rand-wt - pick an item by random, weighting the items with
     *   decreasing probabilities.  The last item is given relative weight
     *   1, the second to last weight 2, the third to last weight 3, etc.
     *   In other words, the nth item from the end of the list is n times
     *   as likely to be picked as the last item.  The picks are
     *   independent.
     *   
     *   seq - run through the items in sequence (1, 2, ... numItems).
     *   
     *   shuffle - run through the list in a shuffled order.
     *   
     *   shuffle2 - shuffle the list into a random order, but only run
     *   through half before reshuffling
     *   
     *   stop - repeat the previous selection forever.  (This should only
     *   be used as the second or later attribute in the list, since it
     *   depends on a prior selection being made.)  
     */
    listAttrs = ''

    /* 
     *   Get the next index value.  Returns an integer from 1 to numItems.
     *   The algorithm for choosing the index depends on the list type, as
     *   defined by listAttrs.  
     */
    getNextIndex()
    {
        /* if we're out of items, generate the next iteration of the list */
        if (idx_ > lst_.length())
        {
            /* pull out the first item from the attributes */
            local alst = listAttrs.split(',', 2);

            /* 
             *   If we have more than one attribute, keep only the
             *   remaining attributes, since the first attribute is for the
             *   first list iteration only. 
             */
            if (alst.length() > 1)
                listAttrs = alst[2];

            /* some of the attributes are interested in the last item */
            local last = lst_.length() >= 1 ? lst_[lst_.length()] : nil;

            /* build the list for the head attribute */
            local pick;
            switch (alst[1])
            {
            case 'stop':
                /* reuse the last item every time from now on */
                lst_ = [last ?? 1];
                break;

            case 'seq':
                /* run through the list in sequence */
                lst_ = List.generate({i: i}, numItems);
                break;
                
            case 'rand':
                /* 
                 *   pick an item at random, independent of other picks -
                 *   just generate a single item list, since we'll want to
                 *   pick at random again next time 
                 */
                lst_ = [rand(numItems) + 1];
                break;

            case 'rand-norpt':
                /* 
                 *   Pick an item at random, but don't repeat the last item
                 *   chosen.  Pick repeatedly until we select an item that
                 *   doesn't match the last selection, if there is one.
                 *   Exception: if the list has only one item, it's
                 *   impossible to choose a different item, so don't try.  
                 */
                do
                {
                    pick = rand(numItems) + 1;
                }
                while (numItems > 1 && pick == last);
                lst_ = [pick];
                break;

            case 'rand-wt':
                /* 
                 *   Pick an item at random, independently of other trials,
                 *   weighting the list in decreasing order of probability.
                 *   The relative weights are 1 for the last item, 2 for
                 *   the second to last item, 3 for the third to last, etc.
                 *   This gives us a total weight of n(n+1)/2, so start by
                 *   picking a number in that range.  1 represents the last
                 *   item, 2..3 the second to last, 3..5 the third, etc.  
                 */
                pick = rand(numItems*(numItems+1)/2) + 1;
                for (local i in 1..numItems ; ; pick -= i)
                {
                    /* if pick is <= i, it's this item */
                    if (pick <= i)
                    {
                        lst_ = [numItems - i + 1];
                        break;
                    }
                }
                break;

            case 'shuffle':
            case 'shuffle2':
                /* 
                 *   Shuffle the list.  Populate the list with the integer
                 *   values from 1 to numItems, then shuffle the list into
                 *   a random order.
                 *   
                 *   The shuffling algorithm, as a physical analogy: Start
                 *   with a deck of cards labeled 1 to numItems.  Put all
                 *   of the cards in a hat.  Pick a card at random from the
                 *   hat and set it aside - call this the "pile".  Pick
                 *   another random card from the hat and put it on the top
                 *   of the pile.  Repeat until the hat is empty.  We now
                 *   have a pile of the cards arranged in random order.
                 *   
                 *   To implement this, we create a vector and fill it with
                 *   integers from 1 to numItems.  Partition the vector
                 *   with an index 'i': items from 1..i are the hat, items
                 *   from i+1..numItems are the deck.  To draw a card at
                 *   random, we pick a random number from 1..i.  To remove
                 *   it from the hat, we swap it into position 'i', because
                 *   that will effectively shrink the hat by one slot and
                 *   grow the pile by one slot.  Decrement i and repeat.  
                 */
                lst_ = Vector.generate({i: i}, numItems);
                for (local i in numItems..2 step -1)
                {
                    /* pick a random element from the remaining set */
                    pick = rand(i) + 1;
                    
                    /* swap the chosen item and the last element */
                    local tmp = lst_[i];
                    lst_[i] = lst_[pick];
                    lst_[pick] = tmp;
                }

                /* 
                 *   The whole point of shuffling is to avoid obvious
                 *   repetition, so make sure we don't repeat any previous
                 *   item from a previous run through the list as the first
                 *   item of the new list.  If the first item matches the
                 *   previous item, reshuffle it into a random spot in the
                 *   list.  (If the list only has one item, of course, this
                 *   is pointless, so don't bother in that case.)  
                 */
                if (lst_[1] == last && numItems > 1)
                {
                    pick = rand(numItems - 1) + 2;
                    lst_[1] = lst_[pick];
                    lst_[pick] = last;
                }

                /* 
                 *   in half-shuffle mode, only keep the first half of the
                 *   list, so that we re-shuffle halfway through 
                 */
                if (alst[1] == 'shuffle2' && numItems > 2)
                    lst_ = lst_.toList(1, numItems/2);
                break;
            }

            /* start from the first item in the list */
            idx_ = 1;
        }

        /* return and consume the next item */
        return lst_[idx_++];
    }

    /* generated list */
    lst_ = []

    /* current position in the list */
    idx_ = 1
;
