::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:
class Assertion.Public  public Gilda: Capture an assertion message and context.

  type Assertion is                 &
      Message   string,             &A message passed from an Assert statement
      Context   string,             &Context associated with the message
      Note      string,             &An additional message
      Method    string,             &Name of the method that failed
      Line      word,               &Assertion line or negative instruction offset
      Fault     Program.Fault       :Enumerated fault codes

  type Program.Fault  in      &Encode ids for Progam Faults.
      Assert.Fault,           & 1 User defined fault.
      Exception.Safe,         & 2 Attempted to propagate an exception from a safe method.
      Exception.Retry,        & 3 Attempted to reenter a handler without a retry.
      Memory.Heap,            & 4 Memory heap overflow.
      Memory.Stack,           & 5 Memory stack overflow.
      Memory.Frame,           & 6 Method stack frame overflow.
      Memory.String,          & 7 String allocation overflow.
      Address.Null,           & 8 Tried to address location 0.
      Address.Low,            & 9 Tried to address below 2^16.
      Address.Protected,      &10 Tried to address protected memory.
      Address.Unmapped,       &11 Tried to address unmapped memory.
      Integer.Divide,         &12 Integer divide by zero.
      Float.Divide,           &13 Floating point divide by zero.
      Float.Underflow,        &14 Floating point underflow.
      Float.Overflow,         &15 Floating point overflow.
      Float.Inexact,          &16 Floating point inexact result.
      Float.Invalid,          &17 Floating point invalid operand.
      Debug.Array,            &18 An array index is out of bounds.
      Debug.Overflow,         &19 Integer overflow.
      Debug.Object,           &20 An object invariant was violated.
      Machine.Check,          &21 An unknown machine check occurred.
      Fault.Retry             :22 An exception occured in a fault handler.

global +Prior      Assertion,   &The previous assertion for nested exceptions.
       +Assertion               :Cm_Run_First_Handler saves the Message and Context.
:
:  Consider elements for:
:     Source module, line, and column.
:     Severity:  Unknown, Memory, Fatal, Warning, Note, Error
:     Error code (aka errno) or other forensic information.
:  These can be managed by a super class as well.
:...............................................................................



::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:
function FORM.PROGRAM.FAULT:  Get a descriptive message about a Fault exception.

 entry Program.Fault            :A Fault code used within First_Handler

  exit Message    string        :A descriptive Fault message
:
:...............................................................................
:
method FIRST.FAULT:  Default library fault handler invoke from First_Handler

 entry Message = ""  string,    &Message passed from an Assert statement
       Context = ""  string,    &Context associated with the message
       Method  = ""  string,    &Name of the method that failed
       Line    = 0   word,      &Line number of the failure
       Fault   = 0   word       :Type code for program faults; else 0
:
:  Set up a drain method to activate managed handlers.
:...............................................................................
:
function ASSERTION.PREFIX:  Split the prefix from the message text.

  exit Prefix  string           :Uppercase prefix (alpha+ ':') sans colon
:
:...............................................................................
:
function ASSERTION.MESSAGE:  Insert a FAULT or ERROR prefix to Assertion`Message.

 entry Context = 0  Bit     :Set to format the context as well.

  exit Message  string      :Prefix followed by Assertion`Message
:
:...............................................................................
:
function FORM..Assertion:  Format the Assertion structure.

 entry Assertion,
       Format = "Raised"  string

  exit Form   string
:
:...............................................................................
:
method SET.ASSERTION.MESSAGE:  Establish an assertion message and prefix.

 entry Prefix  = ""  string,    &Uppercase prefix.
       Message = ""  string     :The message text.
:
: Entry:  By convention the prefix is only alphabetic characters.
:         It is intended to indicate the severity of the message.
:         Common prefixes are:
:             ERROR   - Commonly used on assertions.
:             FAULT   - The program will be terminated.
:             WARNING - The user should decide if an error; processing resumes.
:             NOTE    - Inform the user, but no action is needed.
:             DEBUG   - Only reachable if there is a programmer error.
:...............................................................................
:
method CALL.STACK:  Scan up the call stack for method names and offsets.

  exit Heap..Key..word        :Call stack; bottom is the failing method.

 entry Method = ""   string   :A method name to stop the scan short.
:
:...............................................................................
:
method CLEAR.PROGRAM.FAULT  pure:  Resume processing subsequent handlers after a program fault.
:
:...............................................................................


end