/*

    File:       MoreBBLog.h

    Contains:   Module to log debug traces to BBEdit.

    Written by: Quinn

    Copyright:  Copyright © 2000 by Apple Computer, Inc., all rights reserved.

                You may incorporate this Apple sample source code into your program(s) without

                restriction. This Apple sample source code has been provided "AS IS" and the

                responsibility for its operation is yours. You are not permitted to redistribute

                this Apple sample source code as "Apple sample source code" after having made

                changes. If you're going to re-distribute the source, we require that you make

                it clear in the source that the code was descended from Apple sample source

                code, but that you've made changes.

    Change History (most recent first):

         <2>     20/3/00    Quinn   Expanded and clarified comments.

         <1>      6/3/00    Quinn   First checked in.

*/

#pragma once

/////////////////////////////////////////////////////////////////

// MoreIsBetter Setup

#include "MoreSetup.h"

// Mac OS Interfaces

#include <AppleEvents.h>

/////////////////////////////////////////////////////////////////

#ifdef __cplusplus

extern "C" {

#endif

// Overall Architecture

// --------------------

// This module is designed to allow you to log textual data to BBEdit.

// I used it primarily in MoreOSL to log the progress of my OSL resolution

// and event dispatching.  The nice thing about this is that, when an

// event fails, you can consult the log to find the failure point quickly.

// This is tricky to do otherwise because OSL involves many callbacks,

// which make it hard to follow the flow of control in the debugger.

//

// You can use these routines in any structure (thereÕs no strong

// relationship between the routines) by I typically use the following

// approach:

//

//   1. At application startup, call BBLogStart.

//   2. The debug version of the application has a global "debug"

//      property that scripts can get and set to control the state

//      of logging.  The applicationÕs property setter can control 

//      whether this module logs anything by calling BBLogSetState.

//   3. On entry to a routine, use BBLogLine to log the routineÕs

//      name and BBLogIndent to make the nested log information be

//      nested in the log.

//   4. On exit to a routine, use BBLogOutdentWithErr to both

//      un-indent and log the error result for the routine.

//   5. Inside a routine, use the other routines to log specific

//      data points.  I commonly log the value of incoming parameters

//      at the begging of the routine and the value of outgoing parameters

//      at the end.  I also log important intermediate results.

//

// The following is an imaginary Apple event handler that is marked up

// using BBLog:

//

//  static pascal OSErr MyHandler(const AppleEvent *theEvent, AppleEvent *theReply, UInt32 handlerRefCon)

//  {

//      OSStatus err;

//      AEDesc   dirObjDesc;

//      AEDesc   resolvedDirObToken;

//  

//      BBLogLine("\pAEDispatcher");

//      BBLogIndent();

//      BBLogAppleEvent("\ptheEvent", theEvent);

//      BBLogLong("\phandlerRefCon", handlerRefCon);

//  

//      [.. get the direct object ...]

//

//      err = AEResolve(&dirObjDesc, ..., &resolvedDirObToken);

//      if (err == noErr) {

//          BBLogDesc("\presolvedDirObToken", &resolvedDirObToken);

//      }

//

//      [... handle the event ...]

//      

//      BBLogAppleEvent("\p<theReply", theReply);

//      BBLogOutdentWithErr(err);

//      

//      return err;

//  }

//

// For more examples, take a look at "MoreOSL.c".

//

// To assist in sensible logging, this module installs a bunch of coercion

// handlers to coerce various built-in types to text.  These handlers are

// only installed in the debug version.  You may want to use these handlers

// in other situations.

// The following routines are defined only if youÕre compiling with

// debugging enabled.  Otherwise they are all stubbed out with macros.

#if MORE_DEBUG

    extern pascal void BBLogStart(Boolean logging);

        // Starts the BBEdit logging module and sets the

        // current logging state (if logging is true, logging

        // is on, otherwise itÕs off).  The rest of the routines

        // in this module only produce output is logging is on.

        // 

        // If logging is true, this routine creates a new window in

        // BBEdit for the log data.

    extern pascal void BBLogSetState(Boolean logging);

        // Turns logging on or off.

    extern pascal void BBLogText(void *textPtr, Size textSize);

        // Logs the text buffer to BBEdit, without any formatting

        // or interpretation.

    extern pascal void BBLogLine(ConstStr255Param str);

        // Logs a line of text to BBEdit, adding a time stamp

        // at the front and a CR at the end.  It also indents

        // the line based on the current indent level.

    extern pascal void BBLogIndent(void);

        // Increases the current indent level by 1.

    extern pascal void BBLogOutdent(void);

        // Decreases the current indent level by 1.

    extern pascal void BBLogOutdentWithErr(OSStatus errNum);

        // Decreases the current indent level by 1 and logs

        // a line of text of the form:

        //

        //     err=<decimal representation of errNum>

    extern pascal void BBLogAppleEvent(ConstStr255Param tag, const AppleEvent *theEvent);

        // Logs a line of text of the form:

        // 

        //     <tag>=<text description of theEvent>

    extern pascal void BBLogLong(ConstStr255Param tag,       SInt32 l);

        // Logs a line of text of the form:

        // 

        //     <tag>=<decimal representation of l>

    extern pascal void BBLogDesc(ConstStr255Param tag,       const AEDesc *desc);

        // Logs a line of text of the form:

        // 

        //     <tag>=<text representation of desc>

    extern pascal void BBLogDescType(ConstStr255Param tag,   DescType theType);

        // Logs a line of text of the form:

        // 

        //     <tag>='<theType>'

#else

    #define BBLogStart(logging)

    #define BBLogSetState(logging)

    #define BBLogText(textPtr, textSize)

    #define BBLogLine(str)

    #define BBLogIndent()

    #define BBLogOutdent()

    #define BBLogOutdentWithErr(errNum)

    #define BBLogAppleEvent(tag, theEvent)

    #define BBLogLong(tag, l)

    #define BBLogDesc(tag, desc)

    #define BBLogDescType(tag, theType)

#endif

#ifdef __cplusplus

};

#endif