CodeSnip Old Code (SVN)

{
 * This Source Code Form is subject to the terms of the Mozilla Public License,
 * v. 2.0. If a copy of the MPL was not distributed with this file, You can
 * obtain one at http://mozilla.org/MPL/2.0/
 *
 * Copyright (C) 2005-2012, Peter Johnson (www.delphidabbler.com).
 *
 * $Rev$
 * $Date$
 *
 * Defines application's exception classes and a handler for untrapped
 * exceptions.
}


unit UExceptions;


interface


{
  NOTES:

  Exceptions are treated as bugs unless they derive from ECodeSnip. This means
  that the application needs to trap any expected exceptions that are not
  derived from ECodeSnip.

  The EBug exception class is also provided for explicitly generating bug
  exceptions.

  Untrapped ECodeSnip exceptions result in the display of an error dialog box
  while all others lead to display of a bug report dialog box.
}


uses
  // Delphi
  SysUtils, Controls,
  // Project
  UBaseObjects, UStructs;


type

  TExceptionHelper = class(TNoConstructObject)
  public
    class function Clone(const ExObj: Exception): Exception;
      {Creates a new exception that is an approximate copy of a given exception.
      Any inner exception information is lost. Only the message is copied if the
      exception is not an EAssignable descendant.
        @param ExObj [in] Exception to be cloned. Must be an Exception
          descendant.
        @return New cloned exception.
      }
  end;

  {
  EAssignable:
    Base class for exceptions that can be assigned the properties of another
    exception. Descendants that add extra properties should override Assign to
    copy the extra properties. Descendants may limit the exception classes that
    they accept for assignment.
  }
  EAssignable = class(Exception)
  public
    constructor Create(const E: Exception); overload;
      {Create the exception object with same properties as a given exception.
        @param E [in] Exception to copy.
      }
    procedure Assign(const E: Exception); virtual;
      {Sets this exception object's properties to be the same as another
      exception. Any inner exception information is lost.
        @param E [in] Exception whose properties are to be copied.
      }
  end;

  {
  EBug:
    Base class for exceptions that are treated as bugs.
  }
  EBug = class(EAssignable);

  {
  ECodeSnip:
    Base class for exceptions that are treated as "expected" and are not bugs.
    Such exception must support an Assign method that copies the properties of
    a given exception to the current exception. Descendants that add extra
    properties should extend Assign to copy the extra properties. Descendants
    may limit the exception classes that they accept.
  }
  ECodeSnip = class(EAssignable);

  {
  EValidation:
    Base class fo exceptions that are raised when some kind of validation fails.
    Has a Selection property that may indicate the position and, optionally,
    length of the error, where this makes sense. The HasSelection property is
    set to False when there is no selection information available.
  }
  EValidation = class(ECodeSnip)
  strict private
    var fSelection: TSelection; // Value of Selection property
    var fHasSelection: Boolean; // Value of HasSelection property
    function GetSelection: TSelection;
      {Read accessor for Selection property. Must not be called when
      HasSelection is false.
        @return Value of property.
      }
    procedure SetSelection(const ASelection: TSelection);
      {Write accessor for Selection property. Sets HasSelection to True.
        @param Value [in] New property value.
      }
  public
    constructor Create(const Msg: string; const ASelection: TSelection);
      overload;
      {Creates an exception with a specified message along with selection info.
        @param Msg [in] Exception message.
        @param ASelection [in] Selection information.
      }
    constructor CreateFmt(const Msg: string; const Args: array of const;
      const ASelection: TSelection); overload;
      {Creates an exception with a formatted message along with selection info.
        @param Msg [in] Exception message format string.
        @param Args [in] Message format arguments.
        @param ASelection [in] Selection information.
      }
    procedure Assign(const E: Exception); override;
      {Sets this exception object's properties to be the same as another
      exception.
        @param E [in] Exception whose properties are to be copied. Must be
          another EValidation.
      }
    property HasSelection: Boolean read fHasSelection;
      {Informs if the exception has selection information. When False the
      Selection property cannot be read}
    property Selection: TSelection read GetSelection write SetSelection;
      {Provides information about a selection associated with the exception.
      Cannot be read if HasSelection is false}
  end;

  {
  EDataEntry:
    Class for exception raised during data entry in forms. Carries a reference
    to the control where the error was made. Enables control with erroneous
    entry to be focussed.
  }
  EDataEntry = class(EValidation)
  strict private
    fCtrl: TWinControl; // Value of Ctrl property
  public
    constructor Create(const Msg: string; const Ctrl: TWinControl); overload;
      {Creates an exception with a specified message that refers to a specified
      control.
        @param Msg [in] Exception message.
        @param Ctrl [in] Control to which exception relates.
      }
    constructor Create(const Msg: string; const Ctrl: TWinControl;
      const Selection: TSelection); overload;
      {Creates an exception with a specified message that refers to a specified
      control and selection within it.
        @param Msg [in] Exception message.
        @param Ctrl [in] Control to which exception relates.
        @param Selection [in] Selection containing error in Ctrl.
      }
    constructor CreateFmt(const Msg: string; const Args: array of const;
      const Ctrl: TWinControl; const Selection: TSelection); overload;
      {Creates an exception with a message built from a format string and
      parameters that refers to a specified control and selection within it.
        @param Msg [in] Format string for exception message.
        @param Args [in] Array of arguments for format string.
        @param Ctrl [in] Control to which exception relates.
        @param Selection [in] Selection containing error in Ctrl.
      }
    constructor CreateFmt(const Msg: string; const Args: array of const;
      const Ctrl: TWinControl); overload;
      {Creates an exception with a message built from a format string and
      parameters that refers to a specified control.
        @param Msg [in] Format string for exception message.
        @param Args [in] Array of arguments for format string.
        @param Ctrl [in] Control to which exception relates.
      }
    procedure Assign(const E: Exception); override;
      {Sets this exception object's properties to be the same as another
      exception.
        @param E [in] Exception whose properties are to be copied. Must be
          another EDataEntry.
      }
    property Ctrl: TWinControl read fCtrl;
      {Reference to control to which exception relates}
  end;


implementation


uses
  // Delphi
  Classes;


{ EAssignable }

procedure EAssignable.Assign(const E: Exception);
  {Sets this exception object's properties to be the same as another exception.
  Any inner exception information is lost.
    @param E [in] Exception whose properties are to be copied.
  }
begin
  Self.Message := E.Message;
end;

constructor EAssignable.Create(const E: Exception);
  {Create the exception object with same properties as a given exception.
    @param E [in] Exception to copy.
  }
begin
  inherited Create('');
  Assign(E);  // we call assign so that descendants can copy extra properties
end;

{ EValidation }

procedure EValidation.Assign(const E: Exception);
  {Sets this exception object's properties to be the same as another exception.
    @param E [in] Exception whose properties are to be copied. Must be  another
    EValidation.
  }
begin
  Assert(E is EValidation, ClassName + '.Assign: E must be a EValidation');
  inherited;
  fHasSelection := (E as EValidation).fHasSelection;
  fSelection := (E as EValidation).fSelection;
end;

constructor EValidation.Create(const Msg: string; const ASelection: TSelection);
  {Creates an exception with a specified message along with selection info.
    @param Msg [in] Exception message.
    @param ASelection [in] Selection information.
  }
begin
  inherited Create(Msg);
  SetSelection(ASelection);
end;

constructor EValidation.CreateFmt(const Msg: string; const Args: array of const;
  const ASelection: TSelection);
  {Creates an exception with a formatted message along with selection info.
    @param Msg [in] Exception message format string.
    @param Args [in] Message format arguments.
    @param ASelection [in] Selection information.
  }
begin
  inherited CreateFmt(Msg, Args);
  SetSelection(ASelection);
end;

function EValidation.GetSelection: TSelection;
  {Read accessor for Selection property. Must not be called when
  HasSelection is false.
    @return Value of property.
  }
begin
  Assert(HasSelection,
    ClassName + '.GetPosition: Can''t read Selection property');
  Result := fSelection;
end;

procedure EValidation.SetSelection(const ASelection: TSelection);
  {Write accessor for Selection property. Sets HasSelection to True.
    @param Value [in] New property value.
  }
begin
  fHasSelection := True;
  fSelection := ASelection;
end;

{ EDataEntry }

procedure EDataEntry.Assign(const E: Exception);
  {Sets this exception object's properties to be the same as another
  exception.
    @param E [in] Exception whose properties are to be copied. Must be another
      EDataEntry.
  }
begin
  Assert(E is EDataEntry, ClassName + '.Assign: E must be a EDataEntry');
  inherited;
  fCtrl := (E as EDataEntry).Ctrl;
end;

constructor EDataEntry.Create(const Msg: string; const Ctrl: TWinControl);
  {Creates an exception with a specified message that refers to a specified
  control.
    @param Msg [in] Exception message.
    @param Ctrl [in] Control to which exception relates.
  }
begin
  inherited Create(Msg);
  fCtrl := Ctrl;
end;

constructor EDataEntry.Create(const Msg: string; const Ctrl: TWinControl;
  const Selection: TSelection);
  {Creates an exception with a specified message that refers to a specified
  control and selection within it.
    @param Msg [in] Exception message.
    @param Ctrl [in] Control to which exception relates.
    @param Selection [in] Selection containing error in Ctrl.
  }
begin
  inherited Create(Msg, Selection);
  fCtrl := Ctrl;
end;

constructor EDataEntry.CreateFmt(const Msg: string; const Args: array of const;
  const Ctrl: TWinControl; const Selection: TSelection);
  {Creates an exception with a message built from a format string and parameters
  that refers to a specified control and selection within it.
    @param Msg [in] Format string for exception message.
    @param Args [in] Array of arguments for format string.
    @param Ctrl [in] Control to which exception relates.
    @param Selection [in] Selection containing error in Ctrl.
  }
begin
  inherited CreateFmt(Msg, Args, Selection);
  fCtrl := Ctrl;
end;

constructor EDataEntry.CreateFmt(const Msg: string; const Args: array of const;
  const Ctrl: TWinControl);
  {Creates an exception with a message built from a format string and parameters
  that refers to a specified control.
    @param Msg [in] Format string for exception message.
    @param Args [in] Array of arguments for format string.
    @param Ctrl [in] Control to which exception relates.
  }
begin
  inherited CreateFmt(Msg, Args);
  fCtrl := Ctrl;
end;

{ TExceptionHelper }

class function TExceptionHelper.Clone(const ExObj: Exception): Exception;
  {Creates a new exception that is an approximate copy of a given exception. Any
  inner exception information is lost. Only the message is copied if the
  exception is not an EAssignable descendant.
    @param ExObj [in] Exception to be cloned. Must be an Exception
      descendant.
    @return New cloned exception.
  }
begin
  if ExObj is EAssignable then
  begin
    Result := ExObj.ClassType.Create as EAssignable;
    (Result as EAssignable).Assign(ExObj as EAssignable);
  end
  else
  begin
    Result := ExObj.ClassType.Create as Exception;
    Result.Message := ExObj.Message;
  end;
end;

end.