CodeSnip Old Code (SVN)

{
 * USnippets.pas
 *
 * Defines a singleton object and subsidiary classes that encapsulate the
 * snippets and categories in the CodeSnip database and user defined databases.
 *
 * $Rev$
 * $Date$
 *
 * ***** BEGIN LICENSE BLOCK *****
 *
 * Version: MPL 1.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with the
 * License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
 * the specific language governing rights and limitations under the License.
 *
 * The Original Code is USnippets.pas
 *
 * The Initial Developer of the Original Code is Peter Johnson
 * (http://www.delphidabbler.com/).
 *
 * Portions created by the Initial Developer are Copyright (C) 2005-2009 Peter
 * Johnson. All Rights Reserved.
 *
 * Contributor(s)
 *   NONE
 *
 * ***** END LICENSE BLOCK *****
}


unit USnippets;


interface


uses
  // Delphi
  Classes,
  // Project
  IntfCompilers, UActiveText, UIStringList, ULists, UMultiCastEvents,
  USnippetIDs;


type

  TRoutine = class;
  TRoutineList = class;
  TCategory = class;
  TCategoryList = class;

  {
  TSnippetKind:
    Enumeration of various supported kinds of snippets.
  }
  TSnippetKind = (
    skFreeform,   // free-form code - not in any of other supported formats
    skRoutine,    // procedure or function in standard format
    skConstant,   // constant definition in standard format
    skTypeDef     // type definition in standard format
  );

  {
  TSnippetKinds:
    Sets of snippet kinds.
  }
  TSnippetKinds = set of TSnippetKind;

  {
  TRoutineData:
    Record that provides information about a snippet's properties.
  }
  TRoutineData = record
    Kind: TSnippetKind;               // Kind of snippet
    Cat: string;                      // Category containing snippet
    Desc: string;                     // Description of snippet
    SourceCode: string;               // Snippet's source code
    Extra: IActiveText;               // Extra text used to describe snippet
    CompilerResults: TCompileResults; // Compilation results
    procedure Init;
      {Initialises record by setting default values for fields.
      }
    procedure Assign(const Src: TRoutineData);
      {Sets this record to be a copy of another record.
        @param Src [in] Record to be copied.
      }
  end;

  {
  TRoutineReferences:
    Record that details a snippet's references
  }
  TRoutineReferences = record
    Units: IStringList;         // List of required units
    Depends: ISnippetIDList;    // List of IDs of required snippets
    XRef: ISnippetIDList;       // List of IDs of cross referenced snippets
    procedure Init;
      {Initialises record by creating objects stored in fields.
      }
    procedure Assign(const Src: TRoutineReferences);
      {Sets this record to be a copy of another record.
        @param Src [in] Record to be copied.
      }
  end;

  {
  TRoutineEditData:
    Provides deatils of a snippet's data that can be edited.
  }
  TRoutineEditData = record
    Props: TRoutineData;        // Snippet's editable properties
    Refs: TRoutineReferences;   // Snippet's editable referfences
    procedure Init;
      {Initialises record by creating default values and field objects.
      }
    procedure Assign(const Src: TRoutineEditData);
      {Sets this record to be a copy of another record.
        @param Src [in] Record to be copied.
      }
  end;

  {
  TRoutineInfo:
    Record that encapsulates data read from an import file that describes a
    snippet.
  }
  TRoutineInfo = record
    Name: string;           // Snippet name
    Data: TRoutineEditData; // Describes a snippet
    procedure Assign(const Src: TRoutineInfo);
      {Sets this record's fields to be same as another TRoutineInfo record.
      Object fields are copied appropriately.
        @param Src [in] Record containing fields to be copied.
      }
    procedure Init;
      {Initialises record to nul values.
      }
  end;

  {
  TRoutineInfoList:
    Dynamic array of TRoutineInfo records.
  }
  TRoutineInfoList = array of TRoutineInfo;

  {
  TCategoryData:
    Provides information about a category's properties.
  }
  TCategoryData = record
    Desc: string;     // Description of categpry
    procedure Assign(const Src: TCategoryData);
      {Sets this record's fields to be same as another TCategoryData record.
        @param Src [in] Record containing fields to be copied.
      }
    procedure Init;
      {Initialises record to nul values.
      }
  end;

  {
  TCategoryInfo:
    Record that fully describes a category, i.e. contains all the required data.
  }
  TCategoryInfo = record
    Name: string;         // Name (unique id) of category
    Data: TCategoryData;  // Category's properties
    procedure Assign(const Src: TCategoryInfo);
      {Sets this record's fields to be same as another TCategoryInfo record.
        @param Src [in] Record containing fields to be copied.
      }
    procedure Init;
      {Initialises record to nul values.
      }
  end;

  {
  TSnippetChangeEventKind:
    Enumeration that specifies the different kind of change events triggered by
    the user database.
  }
  TSnippetChangeEventKind = (
    evChangeBegin,          // a change to the database is about to take place
    evChangeEnd,            // a change to the database has completed
    evRoutineAdded,         // a snippet has been added
    evBeforeRoutineDelete,  // a snippet is about to be deleted
    evAfterRoutineDelete,   // a snippet has just been deleted
    evRoutineDeleted,       // a snippet has been deleted
    evRoutineChanged,       // a snippet's properties / references have changed
    evCategoryAdded,        // a category has been added
    evBeforeCategoryDelete, // a category is about to be deleted
    evAfterCategoryDelete,  // a category has just been deleted
    evCategoryDeleted,      // a category has been deleted
    evCategoryChanged       // a category's properties have changed
  );

  {
  ISnippetsDataProvider:
    Interface supported by objects that provides data about the categories and
    snippets in the database.
  }
  ISnippetsDataProvider = interface(IInterface)
    ['{D2D57A0D-DB29-4012-891E-E817E0EED8C8}']
    function GetCategoryProps(const Cat: TCategory): TCategoryData;
      {Retrieves all the properties of a category.
        @param Cat [in] Category for which data is requested.
        @return Record containing property data.
      }
    function GetCategoryRoutines(const Cat: TCategory): IStringList;
      {Retrieves names of all snippets that belong to a category.
        @param Cat [in] Category for which snippet names are requested.
        @return Required list of snippet names.
      }
    function GetRoutineProps(const Routine: TRoutine): TRoutineData;
      {Retrieves all the properties of a snippet.
        @param Routine [in] Snippet for which data is requested.
        @return Record containing property data.
      }
    function GetRoutineRefs(const Routine: TRoutine): TRoutineReferences;
      {Retrieves information about all the references of a snippet.
        @param Routine [in] Snippet for which information is requested.
        @return Record containing references.
      }
  end;

  {
  ISnippetChangeEventInfo:
    Interface supported by objects passed to Snippets object's change event
    handler that provides information about a change event. Some properites
    are not defined for certain event types. Kind property always defined.
  }
  ISnippetChangeEventInfo = interface(IInterface)
    ['{80DEE62F-DC23-4EE7-A0B1-5DE46F483CE1}']
    function GetKind: TSnippetChangeEventKind;
      {Gets kind (type) of event.
        @return Event kind.
      }
    function GetInfo: TObject;
      {Gets additional information about event.
        @return Object that provides required information.
      }
    property Kind: TSnippetChangeEventKind read GetKind;
      {Identifies kind (type) of an event. Always defined}
    property Info: TObject read GetInfo;
      {Provides additional information about the event. Actual type of object
      depends on Kind. May be nil}
  end;

  {
  ISnippetsFactory:
    Interface to factory object that creates snippet and category objects. For
    use by database loader objects.
  }
  ISnippetsFactory = interface(IInterface)
    ['{C6DD85BD-E649-4A90-961C-4011D2714B3E}']
    function CreateCategory(const CatID: string; const UserDefined: Boolean;
      const Data: TCategoryData): TCategory;
      {Creates a new category object.
        @param CatID [in] ID (name) of new category. Must be unique.
        @param UserDefined [in] True if category is user defined, False if not.
        @param Data [in] Record describing category's properties.
        @return Instance of new category object.
      }
    function CreateRoutine(const Name: string; const UserDefined: Boolean;
      const Props: TRoutineData): TRoutine;
      {Creates a new snippet object.
        @param Name [in] Name of new snippet. Must not exist in database
          specified by UserDefined parameter.
        @param UserDefined [in] True if snippet is user defined, False if not.
        @param Props [in] Record describing snippet's properties.
        @return Instance of new snippet with no references.
      }
  end;

  {
  TRoutine:
    Encapsulates a snippet from the database. Can be routine, type, constant or
    free-form.
  }
  TRoutine = class(TObject)
  strict private
    fKind: TSnippetKind;              // Kind of snippet this is
    fCategory: string;                // Name of snippet's category
    fDescription: string;             // Description of snippet
    fSourceCode: string;              // Snippet's source code}
    fName: string;                    // Name of snippet
    fUnits: TStringList;              // List of required units
    fDepends: TRoutineList;           // List of required snippets
    fXRef: TRoutineList;              // List of cross-referenced snippets
    fExtra: IActiveText;              // Additional information about snippet
    fCompatibility: TCompileResults;  // Routine's compiler compatibility
    fUserDefined: Boolean;            // Whether this snippet is user-defined
    function GetID: TSnippetID;
      {Gets snippet's unique ID.
        @return Required ID.
      }
  strict protected
    procedure SetName(const Name: string);
      {Sets Name property.
        @param Name [in] New name.
      }
    procedure SetProps(const Data: TRoutineData);
      {Sets snippet's properties.
        @param Data [in] Record containing property values.
      }
  public
    constructor Create(const Name: string; const UserDefined: Boolean;
      const Props: TRoutineData);
      {Class contructor. Sets up snippet object with given property values.
        @param Name [in] Name of snippet.
        @param UserDefined [in] Indicates if this is a user defined snippet.
        @param Props [in] Values of various snippet properties.
      }
    destructor Destroy; override;
      {Class destructor. Tears down object.
      }
    function IsEqual(const Routine: TRoutine): Boolean;
      {Checks if this snippet is same as another snippet. Snippets are
      considered equal if they have the same name and come from same database.
        @param Routine [in] Snippet being compared.
        @return True if snippets are equal, False if not.
      }
    function CanCompile: Boolean;
      {Checks if snippet can be compiled.
        @return True if compilation supported and False if not.
      }
    property Kind: TSnippetKind read fKind;
      {Kind of snippet represented by this object}
    property ID: TSnippetID read GetID;
      {Snippet's unique ID}
    property Name: string read fName;
      {Name of snippet}
    property Category: string read fCategory;
      {Category to which snippet belongs}
    property Description: string read fDescription;
      {Description of snippet}
    property SourceCode: string read fSourceCode;
      {Source code of snippet}
    property Extra: IActiveText read fExtra;
      {Additional information about snippet}
    property Compatibility: TCompileResults read fCompatibility;
      {Compiler compatibilty of this snippet}
    property Units: TStringList read fUnits;
      {List of units used by snippet}
    property Depends: TRoutineList read fDepends;
      {List of any other snippet in database on which this snippet depends}
    property XRef: TRoutineList read fXRef;
      {List of cross referenced snippets in database}
    property UserDefined: Boolean read fUserDefined;
      {Flag that indicates if this is a user defined snippet}
  end;

  {
  TRoutineList:
    Class that implements a list of TRoutine objects.
  }
  TRoutineList = class(TObject)
  strict private
    function GetItem(Idx: Integer): TRoutine;
      {Read accessor for Items property.
        @param Idx [in] Index of required snippet in list.
        @return Snippet at specified index in list.
      }
    function Find(const RoutineName: string;
      const UserDefined: Boolean; out Index: Integer): Boolean; overload;
      {Finds a snippet in the list that has a specified name and user defined
      property. Uses a binary search.
        @param RoutineName [in] Name of snippet to be found.
        @param UserDefined [in] Whether required snippet is user defined or not.
        @param Index [out] Index of required snippet in list. Valid only if
          method returns True.
        @return True if snippet found, False if not.
      }
    function CompareIDs(const SID1, SID2: TSnippetID): Integer;
      {Compares IDS of two snippets.
        @param SID1 [in] First ID to be compared.
        @param SID2 [in] Second ID to be compared.
        @return 0 if IDs are the same, -ve if SID1 < SID2 and +ve if
          SID1 > SID2.
      }
  strict protected
    var fList: TObjectListEx; // Stores list of snippets
  public
    type
      {
      TEnumerator:
        Implements enumerator for TRoutineList.
      }
      TEnumerator = class(TObject)
      private
        fRoutineList: TRoutineList; // Reference to object being enumerated
        fIndex: Integer;            // Index of current item in enumeration
        function GetCurrent: TRoutine;
          {Gets current snippet in enumeration. Error if at end of enumeration.
            @return Current snippet.
          }
      public
        constructor Create(const RL: TRoutineList);
          {Class constructor. Sets up and initialises enumeration.
            @param RL [in] Reference to snippet list object to be enumerated.
          }
        function MoveNext: Boolean;
          {Moves to next item in enumeration.
            @return True if there is a next item, False if enumeration
              completed.
          }
        property Current: TRoutine read GetCurrent;
          {Current item in enumeration. Error if at end of enumeration}
      end;
  public
    constructor Create(const OwnsObjects: Boolean = False);
      {Class constructor. Creates a new empty list.
        @param OwnsObjects [in] Specifies whether list owns the snippet objects
          it contains. If True the snippets are freed when deleted from list.
      }
    destructor Destroy; override;
      {Class destructor. Tears down object.
      }
    procedure Assign(const SrcList: TRoutineList);
      {Sets this list to be same as another list. List items are referenced, not
      copied.
        @param SrcList [in] List of snippets to be assigned.
      }
    function IsEqual(const AList: TRoutineList): Boolean;
      {Checks if this list contains same snippets as another list.
        @param AList [in] List of snippets to compare.
        @return True if lists are same, False if not.
      }
    function Add(const Routine: TRoutine): Integer; virtual;
      {Adds new snippet to the list, maintaining list in alphabetical order.
        @param Routine [in] Snippet being added.
        @return Index where item was inserted in list
        @except Raised if duplicate snippet added to list.
      }
    function Find(const RoutineName: string;
      const UserDefined: Boolean): TRoutine; overload;
      {Finds a named snippet in list with a matching user defined property.
        @param RoutineName [in] Name of required snippet.
        @param UserDefined [in] Flag that determines if we are looking for a
          user defined snippet or one from main database.
        @return Reference to object representing snippet in list or nil if not
          in list.
      }
    function Contains(const Routine: TRoutine): Boolean;
      {Checks whether list contains a specified snippet.
        @param Routine [in] Required snippet.
        @return True if snippet is in list, False otherwise.
      }
    function ContainsKinds(const Kinds: TSnippetKinds): Boolean;
      {Checks if the list contains specified kinds of snippets.
        @param Kinds [in] Set of kinds to test for.
        @return True if list contains at least one snippet of any of the
          specified kinds.
      }
    procedure Clear;
      {Clears the list.
      }
    function GetEnumerator: TEnumerator;
      {Gets an intialised snippet list enumerator.
        @return Required enumerator.
      }
    function Count(const UserDefined: Boolean): Integer; overload;
      {Counts number of snippets in list that are either from or not from user
      defined database.
        @param UserDefined [in] Flags whether to count snippets in user database
          (True) or in main database (False).
        @return Number of snippets in specified database.
      }
    function Count: Integer; overload;
      {Counts number of snippets in list.
        @return Number of snippets in list.
      }
    property Items[Idx: Integer]: TRoutine read GetItem; default;
      {List of snippets}
  end;

  {
  TCategory:
    Class that encapsulates a codesnip database category and list of all
    snippets in it.
  }
  TCategory = class(TObject)
  strict private
    fRoutines: TRoutineList;  // List of snippet objects in category
    fCategory: string;        // Category name
    fDescription: string;     // Category description
    fUserDefined: Boolean;    // Whether this is a user-defined snippet
  public
    constructor Create(const CatID: string; const UserDefined: Boolean;
      const Data: TCategoryData);
      {Class contructor. Sets up category object with given property values.
        @param Data [in] Contains required property values.
      }
    destructor Destroy; override;
      {Class destructor. Tears down object.
      }
    function IsEqual(const Cat: TCategory): Boolean;
      {Checks if this category is same as another category. Categories are
      considered equal if they have the same name.
        @param Cat [in] Category being compared.
        @return True if categories are equal, False if not.
      }
    property Category: string read fCategory;
      {Category name. Must be unique}
    property Description: string read fDescription;
      {Description of category}
    property Routines: TRoutineList read fRoutines;
      {List of snippets in this category}
    property UserDefined: Boolean read fUserDefined;
      {Flag that indicates if this is a user defined category}
  end;

  {
  TCategoryList:
    Class that implements a list of TCategory objects.
  }
  TCategoryList = class(TObject)
  strict private
    function GetCount: Integer;
      {Read accessor for Count property.
        @return Number of categories in list.
      }
    function GetItem(Idx: Integer): TCategory;
      {Read accessor for Items property.
        @param Idx [in] Index of required category in list.
        @return Category at specified index in list.
      }
  strict protected
    var fList: TObjectListEx; // Stores list of categories
  public
    type
      {
      TEnumerator:
        Implements enumerator for TCategoryList.
      }
      TEnumerator = class(TObject)
      private
        fCategoryList: TCategoryList;   // Category list being enumerated
        fIndex: Integer;                // Index of current item in enumeration
        function GetCurrent: TCategory;
          {Gets current category in enumeration. Error if at end of enumeration.
            @return Current category.
          }
      public
        constructor Create(const CL: TCategoryList);
          {Class constructor. Sets up and initialises enumeration.
            @param CL [in] Reference to object to be enumerated.
          }
        function MoveNext: Boolean;
          {Moves to next item in enumeration.
            @return True if there is a next item, False if enumeration
              completed.
          }
        property Current: TCategory read GetCurrent;
          {Current item in enumeration. Error if at end of enumeration}
      end;
  public
    constructor Create(const OwnsObjects: Boolean = False);
      {Class constructor. Creates a new empty list.
        @param OwnsObjects [in] Specifies whether list owns the category objects
          it contains. If True the categories are freed when deleted from list.
      }
    destructor Destroy; override;
      {Class destructor. Tears down object.
      }
    procedure Clear;
      {Clears the list.
      }
    function Add(const Category: TCategory): Integer;
      {Adds new category to list.
        @param Category [in] Category to be added.
        @return Index where category inserted in list.
      }
    function Find(const CatName: string): TCategory;
      {Finds a named category in list.
        @param CatName [in] Name of required category.
        @return Reference to object representing category in list or nil if not
          in list.
      }
    function Contains(const Category: TCategory): Boolean;
      {Checks if a category is in list. Checks object reference.
        @param Category [in] Category to be checked.
        @return True if category object is in list.
      }
    function GetEnumerator: TEnumerator;
      {Gets an intialised category list enumerator.
        @return Required enumerator.
      }
    property Items[Idx: Integer]: TCategory read GetItem; default;
      {List of categories}
    property Count: Integer read GetCount;
      {Number of categories in list}
  end;

  {
  ISnippets:
    Interface to object that encapsulates the whole (main and user) databases
    and provides access to all snippets and all categories.
  }
  ISnippets = interface(IInterface)
    ['{A280DEEF-0336-4264-8BD0-7CDFBB207D2E}']
    procedure Load;
      {Loads data from main and user databases.
      }
    procedure Clear;
      {Clears all data.
      }
    procedure AddChangeEventHandler(const Handler: TNotifyEventInfo);
      {Adds a change event handler to list of listeners.
        @param Handler [in] Event handler to be added.
      }
    procedure RemoveChangeEventHandler(const Handler: TNotifyEventInfo);
      {Removes a change event handler from list of listeners.
        @param Handler [in] Handler to remove from list.
      }
    function GetRoutines: TRoutineList;
      {Gets list of snippets in main and user databases.
        @return Required list.
      }
    function GetCategories: TCategoryList;
      {Gets list of categories in main and user databases.
        @return Required list.
      }
    property Categories: TCategoryList read GetCategories;
      {List of categories in main and user databases}
    property Routines: TRoutineList read GetRoutines;
      {List of snippets in main and user databases}
  end;

  {
  ISnippetsEdit:
    Interface to object that can be used to edit the user database.
  }
  ISnippetsEdit = interface(IInterface)
    ['{CBF6FBB0-4C18-481F-A378-84BB09E5ECF4}']
    function GetEditableRoutineInfo(
      const Routine: TRoutine = nil): TRoutineEditData;
      {Provides details of all a snippet's data (properties and references) that
      may be edited.
        @param Routine [in] Snippet for which data is required. May be nil in
          which case a blank record is returned.
        @return Required data.
      }
    function GetDependents(const Routine: TRoutine): ISnippetIDList;
      {Builds an ID list of all snippets that depend on a specified snippet.
        @param Routine [in] Snippet for which dependents are required.
        @return List of IDs of dependent snippets.
      }
    function GetReferrers(const Routine: TRoutine): ISnippetIDList;
      {Builds an ID list of all snippets that cross reference a specified
      snippet.
        @param Routine [in] Snippet for which cross referers are required.
        @return List of IDs of referring snippets.
      }
    function UpdateRoutine(const Routine: TRoutine;
      const Data: TRoutineEditData; const NewName: string = ''): TRoutine;
      {Updates a user defined snippet's properties and references using provided
      data.
        @param Routine [in] Snippet to be updated. Must be user-defined.
        @param Data [in] Record containing revised data.
        @param NewName [in] New name of snippet. Set to '' or Routine.Name if
          name is not to change.
        @return Reference to updated snippet. Will have changed.
      }
    function AddRoutine(const RoutineName: string;
      const Data: TRoutineEditData): TRoutine;
      {Adds a new snippet to the user database.
        @param RoutineName [in] Name of new snippet.
        @param Data [in] Record storing new snippet's properties and references.
        @return Reference to new snippet.
      }
    function CreateTempRoutine(const RoutineName: string;
      const Data: TRoutineEditData): TRoutine; overload;
      {Creates a new temporary snippet without adding it to the Snippets
      object's snippets list. The new instance may not be added to the
      Snippets object.
        @param RoutineName [in] Name of new snippet.
        @param Data [in] Record storing new snippet's properties and references.
        @return Reference to new snippet.
      }
    function CreateTempRoutine(const Routine: TRoutine): TRoutine; overload;
      {Creates a new temporary copy of a snippet without adding it to the
      Snippets object's snippets list. The new instance may not be added to the
      Snippets object.
        @param Routine [in] Snippet to be copied.
        @return Reference to new copied snippet.
      }
    procedure DeleteRoutine(const Routine: TRoutine);
      {Deletes a snippet from the user database.
        @param Routine [in] Snippet to be deleted.
      }
    function GetEditableCategoryInfo(
      const Category: TCategory = nil): TCategoryData;
      {Provides details of all a category's data that may be edited.
        @param Category [in] Category for which data is required. May be nil in
          whih case a blank record is returned.
        @return Required data.
      }
    function AddCategory(const CatName: string;
      const Data: TCategoryData): TCategory;
      {Adds a new category to the user database.
        @param CatName [in] Name of new category.
        @param Data [in] Record storing new category's properties.
        @return Reference to new category.
      }
    function UpdateCategory(const Category: TCategory;
      const Data: TCategoryData): TCategory;
      {Updates a user defined category's properties.
        @param Category [in] Category to be updated. Must be user-defined.
        @param Data [in] Record containing revised data.
        @return Reference to updated category. Will have changed.
      }
    procedure DeleteCategory(const Category: TCategory);
      {Deletes a category and all its snippets from the user database.
        @param Category [in] Category to be deleted.
      }
    function Updated: Boolean;
      {Checks if user database has been updated since last save.
        @return True if database has been updated, False otherwise.
      }
    procedure Save;
      {Saves user database.
      }
  end;


function Snippets: ISnippets;
  {Returns singleton instance of object that encapsulates main and user
  databases.
    @return Singleton object.
  }


implementation


uses
  // Delphi
  SysUtils, Windows {for inlining},
  // Project
  IntfCommon, UExceptions, USnippetsIO;


var
  // Private global snippets singleton object
  PvtSnippets: ISnippets = nil;


type

  {
  TSnippetsFactory:
    Class that can create category and snippet objects.
  }
  TSnippetsFactory = class(TInterfacedObject, ISnippetsFactory)
  public
    function CreateCategory(const CatID: string; const UserDefined: Boolean;
      const Data: TCategoryData): TCategory;
      {Creates a new category object.
        @param CatID [in] ID (name) of new category. Must be unique.
        @param UserDefined [in] True if category is user defined, False if not.
        @param Data [in] Record describing category's properties.
        @return Instance of new category object.
      }
    function CreateRoutine(const Name: string; const UserDefined: Boolean;
      const Props: TRoutineData): TRoutine;
      {Creates a new snippet object.
        @param Name [in] Name of new snippet. Must not exist in database
          specified by UserDefined parameter.
        @param UserDefined [in] True if snippet is user defined, False if not.
        @param Props [in] Record describing snippet's properties.
        @return Instance of new snippet with no references.
      }
  end;

  {
  TRoutineEx:
    Private extension of TRoutine for use internally by Snippets object.
  }
  TRoutineEx = class(TRoutine)
  public
    procedure UpdateRefs(const Refs: TRoutineReferences;
      const AllRoutines: TRoutineList);
      {Updates a snippet's references.
        @param Refs [in] Stores all snippet's references (XRef, Depends and
          Units).
        @param AllRoutines [in] List of all snippets in database.
      }
    procedure Update(const Data: TRoutineEditData;
      const AllRoutines: TRoutineList);
      {Updates snippet's properties and references.
        @param Data [in] New property values and references.
        @param AllRoutines [in] List of all snippets in database.
      }
    function GetEditData: TRoutineEditData;
      {Gets details of all editable data of snippet.
        @return Required editable properties and references.
      }
    function GetProps: TRoutineData;
      {Gets details of snippet's properties.
        @return Record containing property values.
      }
    function GetReferences: TRoutineReferences;
      {Gets details of snippet's references.
        @return Information sufficient to define references.
      }
  end;

  {
  TTempRoutine:
    Special subclass of TRoutineEx that can't be added to the Snippets object.
    Class does nothing, simply provides a class name for testing when a snippet
    is added to a TRoutineListEx. TTempRoutine can be added to a normal snippet
    list.
  }
  TTempRoutine = class(TRoutineEx);

  {
  TRoutineListEx:
    Private extension of TRoutineList for use internally by Snippets object.
  }
  TRoutineListEx = class(TRoutineList)
  public
    function Add(const Routine: TRoutine): Integer; override;
      {Adds a snippet to list. Prevents TTempRoutine instances from being added.
        @param Routine [in] Snippet to be added.
        @return Index where snippet was added to list.
        @except EBug raised if Routine is a TTempRoutine instance.
      }
    procedure Delete(const Routine: TRoutine);
      {Deletes a snippet from list.
        @param Routine [in] Snippet to be deleted. No action taken if snippet
          not in list.
      }
  end;

  {
  TCategoryEx:
    Private extension of TCategory for use internally by Snippets object.
  }
  TCategoryEx = class(TCategory)
  public
    function GetEditData: TCategoryData;
      {Gets details of all editable data of category.
        @return Required editable data.
      }
  end;

  {
  TCategoryListEx:
    Private extension of TCategoryList for use internally by snippets object.
  }
  TCategoryListEx = class(TCategoryList)
  public
    procedure Delete(const Category: TCategory);
      {Deletes a category from the list.
        @param Category [in] Category to be deleted.
      }
  end;

  {
  TSnippets:
    Class that encapsulates the main and user databases. Provides access to all
    snippets and all categories via the ISnippets interface. Also enables user
    defined database to be modified via ISnippetsEdit interface.
  }
  TSnippets = class(TInterfacedObject,
    ISnippets,
    ISnippetsEdit
  )
  strict private
    fUpdated: Boolean;                // Flags if user database has been updated
    fCategories: TCategoryList;       // List of categories
    fRoutines: TRoutineList;          // List of snippets
    fChangeEvents: TMulticastEvents;  // List of change event handlers
    type
      {
      TEventInfo:
        Class that provides information about a change event.
      }
      TEventInfo = class(TInterfacedObject, ISnippetChangeEventInfo)
      strict private
        fKind: TSnippetChangeEventKind; // Kind of event
        fInfo: TObject;                 // Extra info about event
      protected // do not make strict
        { ISnippetChangeEventInfo methods }
        function GetKind: TSnippetChangeEventKind;
          {Gets kind (type) of event.
            @return Event kind.
          }
        function GetInfo: TObject;
          {Gets additional information about event.
            @return Object that provides required information.
          }
      public
        constructor Create(const Kind: TSnippetChangeEventKind;
          const Info: TObject = nil);
          {Class constructor. Creates an event information object.
            @param Kind [in] Kind of event.
            @param Info [in] Reference to further information about the event.
               May be nil if event doesn't have additional information.
          }
      end;
    procedure TriggerEvent(const Kind: TSnippetChangeEventKind;
      const Info: TObject = nil);
      {Triggers a change event. Notifies all registered listeners.
        @param Kind [in] Kind of event.
        @param Info [in] Reference to any further information for event. May be
          nil.
      }
    function InternalAddRoutine(const RoutineName: string;
      const Data: TRoutineEditData): TRoutine;
      {Adds a new snippet to the user database. Assumes snippet not already in
      user database.
        @param RoutineName [in] Name of new snippet.
        @param Data [in] Properties and references of new snippet.
        @return Reference to new snippet object.
        @except Exception raised if snippet's category does not exist.
      }
    procedure InternalDeleteRoutine(const Routine: TRoutine);
      {Deletes a snippet from the user database.
        @param Routine [in] Snippet to delete from database.
      }
    function InternalAddCategory(const CatName: string;
      const Data: TCategoryData): TCategory;
      {Adds a new category to the user database. Assumes category not already in
      user database.
        @param CatName [in] Name of new category.
        @param Data [in] Properties of new category.
        @return Reference to new category object.
      }
    procedure InternalDeleteCategory(const Cat: TCategory);
      {Deletes a category from the user database.
        @param Cat [in] Category to delete from database.
      }
    procedure GetDependentList(const ARoutine: TRoutine;
      const List: TRoutineList);
      {Builds a list of all snippets that depend on a specified snippet.
        @param ARoutine [in] Snippet for which dependents are required.
        @param List [in] Receives list of dependent snippets.
      }
    procedure GetReferrerList(const ARoutine: TRoutine;
      const List: TRoutineList);
      {Builds list of all snippets that cross reference a specified snippet.
        @param ARoutine [in] The cross referenced snippet.
        @param List [in] Receives list of cross referencing snippets.
      }
  protected
    { ISnippets methods }
    function GetCategories: TCategoryList;
      {Gets list of all categories in database.
        @return Required list.
      }
    function GetRoutines: TRoutineList;
      {Gets list of all snippets in database.
        @return Required list.
      }
    procedure Load;
      {Loads object's data from main and user defined databases.
      }
    procedure Clear;
      {Clears the object's data.
      }
    procedure AddChangeEventHandler(const Handler: TNotifyEventInfo);
      {Adds a change event handler to list of listeners.
        @param Handler [in] Event handler to be added.
      }
    procedure RemoveChangeEventHandler(const Handler: TNotifyEventInfo);
      {Removes a change event handler from list of listeners.
        @param Handler [in] Handler to remove from list.
      }
    { ISnippetsEdit methods }
    function GetEditableRoutineInfo(
      const Routine: TRoutine = nil): TRoutineEditData;
      {Provides details of all a snippet's data (properties and references) that
      may be edited.
        @param Routine [in] Snippet for which data is required. May be nil in
          which case a blank record is returned.
        @return Required data.
      }
    function GetDependents(const Routine: TRoutine): ISnippetIDList;
      {Builds an ID list of all snippets that depend on a specified snippet.
        @param Routine [in] Snippet for which dependents are required.
        @return List of IDs of dependent snippets.
      }
    function GetReferrers(const Routine: TRoutine): ISnippetIDList;
      {Builds an ID list of all snippets that cross reference a specified
      snippet.
        @param Routine [in] Snippet which is cross referenced.
        @return List of IDs of referring snippets.
      }
    function UpdateRoutine(const Routine: TRoutine;
      const Data: TRoutineEditData; const NewName: string = ''): TRoutine;
      {Updates a user defined snippet's properties and references using provided
      data.
        @param Routine [in] Snippet to be updated. Must be user-defined.
        @param Data [in] Record containing revised data.
        @param NewName [in] New name of snippet. Set to '' or Routine.Name if
          name is not to change.
        @return Reference to updated snippet. Will have changed.
      }
    function AddRoutine(const RoutineName: string;
      const Data: TRoutineEditData): TRoutine;
      {Adds a new snippet to the user database.
        @param RoutineName [in] Name of new snippet.
        @param Data [in] Record storing new snippet's properties and references.
        @return Reference to new snippet.
      }
    function CreateTempRoutine(const RoutineName: string;
      const Data: TRoutineEditData): TRoutine; overload;
      {Creates a new temporary user defined snippet without adding it to the
      Snippets object's snippets list. The new instance may not be added to the
      Snippets object.
        @param RoutineName [in] Name of new snippet.
        @param Data [in] Record storing new snippet's properties and references.
        @return Reference to new snippet.
      }
    function CreateTempRoutine(const Routine: TRoutine): TRoutine; overload;
      {Creates a new temporary copy of a snippet without adding it to the
      Snippets object's snippets list. The new instance may not be added to the
      Snippets object.
        @param Routine [in] Snippet to be copied.
        @return Reference to new snippet.
      }
    procedure DeleteRoutine(const Routine: TRoutine);
      {Deletes a snippet from the user database.
        @param Routine [in] Snippet to be deleted.
      }
    function GetEditableCategoryInfo(
      const Category: TCategory = nil): TCategoryData;
      {Provides details of all a category's data that may be edited.
        @param Category [in] Category for which data is required. May be nil in
          which case a blank record is returned.
        @return Required data.
      }
    function AddCategory(const CatName: string;
      const Data: TCategoryData): TCategory;
      {Adds a new category to the user database.
        @param CatName [in] Name of new category.
        @param Data [in] Record storing new category's properties.
        @return Reference to new category.
      }
    function UpdateCategory(const Category: TCategory;
      const Data: TCategoryData): TCategory;
      {Updates a user defined category's properties.
        @param Category [in] Category to be updated. Must be user-defined.
        @param Data [in] Record containing revised data.
        @return Reference to updated category. Will have changed.
      }
    procedure DeleteCategory(const Category: TCategory);
      {Deletes a category and all its snippets from the user database.
        @param Category [in] Category to be deleted.
      }
    function Updated: Boolean;
      {Checks if user database has been updated since last save.
        @return True if database has been updated, False otherwise.
      }
    procedure Save;
      {Saves user defined snippets and all categories to user database.
      }
  public
    constructor Create;
      {Class constructor. Sets up new empty object.
      }
    destructor Destroy; override;
      {Class destructor. Tidies up and tears down object.
      }
  end;

  {
  TUserDataProvider:
    Class that provides data about the categories and snippets in the user-
    defined database.
  }
  TUserDataProvider = class(TInterfacedObject, ISnippetsDataProvider)
  strict private
    fRoutines: TRoutineList;    // All snippets in the whole database
    fCategories: TCategoryList; // All categories in the whole database
  public
    constructor Create(const Routines: TRoutineList;
      const Categories: TCategoryList);
      {Class constructor. Records list of all snippets and categories in both
      databases.
        @param Routines [in] List of all snippets in whole database.
        @param Categories [in] List of all categories in whole database.
      }
    { ISnippetsDataProvider methods }
    function GetCategoryProps(const Cat: TCategory): TCategoryData;
      {Retrieves all the properties of a category.
        @param Cat [in] Category for which data is requested.
        @return Record containing property data.
      }
    function GetCategoryRoutines(const Cat: TCategory): IStringList;
      {Retrieves names of all user-defined snippets that belong to a category.
        @param Cat [in] Category for which snippet names are requested.
        @return Required list of snippet names.
      }
    function GetRoutineProps(const Routine: TRoutine): TRoutineData;
      {Retrieves all the properties of a snippet.
        @param Routine [in] Snippet for which data is requested.
        @return Record containing property data.
      }
    function GetRoutineRefs(const Routine: TRoutine): TRoutineReferences;
      {Retrieves information about all the references of a snippet.
        @param Routine [in] Snippet for which information is requested.
        @return Record containing references.
      }
  end;

  {
  TSnippetIDListEx:
    Extension of TSnippetIDList that provides an additional constructor that can
    create a snippet ID list from a TRoutineList.
  }
  TSnippetIDListEx = class(TSnippetIDList)
  public
    constructor Create(const Routines: TRoutineList); overload;
      {Class constructor overload that creates a snippets ID list from a
      TRoutineList object.
        @param Routines [in] List of snippets objects for which ID list is
          required.
      }
  end;

function Snippets: ISnippets;
  {Returns singleton instance of object that encapsulates main and user
  databases.
    @return Singleton object.
  }
begin
  if not Assigned(PvtSnippets) then
    PvtSnippets := TSnippets.Create;
  Result := PvtSnippets;
end;

{ TSnippets }

function TSnippets.AddCategory(const CatName: string;
  const Data: TCategoryData): TCategory;
  {Adds a new category to the user database.
    @param CatName [in] Name of new category.
    @param Data [in] Record storing new category's properties.
    @return Reference to new category.
  }
resourcestring
  // Error message
  sNameExists = 'Category %s already exists in user database';
begin
  Result := nil;
  TriggerEvent(evChangeBegin);
  try
    // Check if category with same name exists in user database: error if so
    if fCategories.Find(CatName) <> nil then
      raise ECodeSnip.CreateFmt(sNameExists, [CatName]);
    Result := InternalAddCategory(CatName, Data);
    TriggerEvent(evCategoryAdded, Result);
  finally
    fUpdated := True;
    TriggerEvent(evChangeEnd);
  end;
end;

procedure TSnippets.AddChangeEventHandler(const Handler: TNotifyEventInfo);
  {Adds a change event handler to list of listeners.
    @param Handler [in] Event handler to be added.
  }
begin
  fChangeEvents.AddHandler(Handler);
end;

function TSnippets.AddRoutine(const RoutineName: string;
  const Data: TRoutineEditData): TRoutine;
  {Adds a new snippet to the user database.
    @param RoutineName [in] Name of new snippet.
    @param Data [in] Record storing new snippet's properties and references.
    @return Reference to new snippet.
  }
resourcestring
  // Error message
  sNameExists = 'Snippet "%s" already exists in user database';
begin
  Result := nil;  // keeps compiler happy
  TriggerEvent(evChangeBegin);
  try
    // Check if snippet with same name exists in user database: error if so
    if fRoutines.Find(RoutineName, True) <> nil then
      raise ECodeSnip.CreateFmt(sNameExists, [RoutineName]);
    Result := InternalAddRoutine(RoutineName, Data);
    TriggerEvent(evRoutineAdded, Result);
  finally
    fUpdated := True;
    TriggerEvent(evChangeEnd);
  end;
end;

procedure TSnippets.Clear;
  {Clears the object's data.
  }
begin
  fCategories.Clear;
  fRoutines.Clear;
end;

constructor TSnippets.Create;
  {Class constructor. Sets up new empty object.
  }
begin
  inherited Create;
  fRoutines := TRoutineListEx.Create(True);
  fCategories := TCategoryListEx.Create(True);
  fChangeEvents := TMultiCastEvents.Create(Self);
end;

function TSnippets.CreateTempRoutine(const Routine: TRoutine): TRoutine;
  {Creates a new temporary copy of a snippet without adding it to the
  Snippets object's snippets list. The new instance may not be added to the
  Snippets object.
    @param Routine [in] Snippet to be copied.
    @return Reference to new snippet.
  }
var
  Data: TRoutineEditData; // data describing snippet's properties and references
begin
  Assert(Assigned(Routine), ClassName + '.CreateTempRoutine: Routine is nil');
  Assert(Routine is TRoutineEx,
    ClassName + '.CreateTempRoutine: Routine is not a TRoutineEx');
  Data := (Routine as TRoutineEx).GetEditData;
  Result := TTempRoutine.Create(
    Routine.Name, Routine.UserDefined, (Routine as TRoutineEx).GetProps);
  (Result as TTempRoutine).UpdateRefs(
    (Routine as TRoutineEx).GetReferences, fRoutines
  );
end;

function TSnippets.CreateTempRoutine(const RoutineName: string;
  const Data: TRoutineEditData): TRoutine;
  {Creates a new temporary user defined snippet without adding it to the
  Snippets object's snippets list. The new instance may not be added to the
  Snippets object.
    @param RoutineName [in] Name of new snippet.
    @param Data [in] Record storing new snippet's properties and references.
    @return Reference to new snippet.
  }
begin
  Result := TTempRoutine.Create(RoutineName, True, Data.Props);
  (Result as TTempRoutine).UpdateRefs(Data.Refs, fRoutines);
end;

procedure TSnippets.DeleteCategory(const Category: TCategory);
  {Deletes a category and all its snippets from the user database.
    @param Category [in] Category to be deleted.
  }
var
  SnipIdx: Integer; // loops thru all category's snippets
begin
  Assert(Category.UserDefined,
    ClassName + '.DeleteCategory: Category is not user defined');
  Assert(fCategories.Contains(Category),
    ClassName + '.DeleteCategory: Category is not in the database');
  TriggerEvent(evChangeBegin);
  try
    // all snippets that belong to category are deleted before category itself
    // can't use for..in here since Routines list is modified in loop
    for SnipIdx := Pred(Category.Routines.Count) downto 0 do
      InternalDeleteRoutine(Category.Routines[SnipIdx]);
    InternalDeleteCategory(Category);
    TriggerEvent(evCategoryDeleted);
  finally
    TriggerEvent(evChangeEnd);
    fUpdated := True;
  end;
end;

procedure TSnippets.DeleteRoutine(const Routine: TRoutine);
  {Deletes a snippet from the user database.
    @param Routine [in] Snippet to be deleted.
  }
var
  Dependent: TRoutine;      // loops thru each snippet that depends on Routine
  Dependents: TRoutineList; // list of dependent snippets
  Referrer: TRoutine;       // loops thru snippets that cross references Routine
  Referrers: TRoutineList;  // list of referencing snippets
begin
  Assert(Routine.UserDefined,
    ClassName + '.DeleteRoutine: Routine is not user-defined');
  Assert(fRoutines.Contains(Routine),
    ClassName + '.DeleteRoutine: Routine is not in the database');
  TriggerEvent(evChangeBegin);
  // Get list of referencing and dependent routines
  Dependents := nil;
  Referrers := nil;
  try
    Dependents := TRoutineList.Create;
    GetDependentList(Routine, Dependents);
    Referrers := TRoutineList.Create;
    GetReferrerList(Routine, Referrers);
    // Delete routine for XRef or Depends list of referencing snippets
    for Referrer in Referrers do
      (Referrer.XRef as TRoutineListEx).Delete(Routine);
    for Dependent in Dependents do
      (Dependent.Depends as TRoutineListEx).Delete(Routine);
    // Delete routine itself
    InternalDeleteRoutine(Routine);
    TriggerEvent(evRoutineDeleted);
  finally
    FreeAndNil(Referrers);
    FreeAndNil(Dependents);
    fUpdated := True;
    TriggerEvent(evChangeEnd);
  end;
end;

destructor TSnippets.Destroy;
  {Class destructor. Tidies up and tears down object.
  }
begin
  FreeAndNil(fChangeEvents);
  FreeAndNil(fCategories);
  FreeAndNil(fRoutines);
  inherited;
end;

function TSnippets.GetCategories: TCategoryList;
  {Gets list of all categories in database.
    @return Required list.
  }
begin
  Result := fCategories;
end;

procedure TSnippets.GetDependentList(const ARoutine: TRoutine;
  const List: TRoutineList);
  {Builds a list of all snippets that depend on a specified snippet.
    @param ARoutine [in] Snippet for which dependents are required.
    @param List [in] Receives list of dependent snippets.
  }
var
  Routine: TRoutine;  // references each snippet in database
begin
  List.Clear;
  for Routine in fRoutines do
    if not Routine.IsEqual(ARoutine) and Routine.Depends.Contains(ARoutine) then
      List.Add(Routine);
end;

function TSnippets.GetDependents(const Routine: TRoutine): ISnippetIDList;
  {Builds an ID list of all snippets that depend on a specified snippet.
    @param Routine [in] Snippet for which dependents are required.
    @return List of IDs of dependent snippets.
  }
var
  List: TRoutineList; // list of dependent snippets
begin
  List := TRoutineList.Create;
  try
    GetDependentList(Routine, List);
    Result := TSnippetIDListEx.Create(List);
  finally
    FreeAndNil(List);
  end;
end;

function TSnippets.GetEditableCategoryInfo(
  const Category: TCategory): TCategoryData;
  {Provides details of all a category's data that may be edited.
    @param Category [in] Category for which data is required. May be nil in
      whih case a blank record is returned.
    @return Required data.
  }
begin
  Assert(not Assigned(Category) or Category.UserDefined,
    ClassName + '.GetEditableCategoryInfo: Category is not user-defined');
  if Assigned(Category) then
  else
    Result.Init;
end;

function TSnippets.GetEditableRoutineInfo(
  const Routine: TRoutine): TRoutineEditData;
  {Provides details of all a snippet's data (properties and references) that may
  be edited.
    @param Routine [in] Snippet for which data is required. May be nil in which
      case a blank record is returned.
    @return Required data.
  }
begin
  Assert(not Assigned(Routine) or Routine.UserDefined,
    ClassName + '.GetEditableRoutineInfo: Routine is not user-defined');
  if Assigned(Routine) then
    Result := (Routine as TRoutineEx).GetEditData
  else
    Result.Init;
end;

function TSnippets.GetReferrers(const Routine: TRoutine): ISnippetIDList;
  {Builds an ID list of all snippets that cross reference a specified
  snippet.
    @param Routine [in] Snippet which is cross referenced.
    @return List of IDs of referring snippets.
  }
var
  List: TRoutineList; // list of referring snippets
begin
  List := TRoutineList.Create;
  try
    GetReferrerList(Routine, List);
    Result := TSnippetIDListEx.Create(List);
  finally
    FreeAndNil(List);
  end;
end;

procedure TSnippets.GetReferrerList(const ARoutine: TRoutine;
  const List: TRoutineList);
  {Builds list of all snippets that cross reference a specified snippet.
    @param ARoutine [in] The cross referenced snippet.
    @param List [in] Receives list of cross referencing snippets.
  }
var
  Routine: TRoutine;  // references each routine in database
begin
  List.Clear;
  for Routine in fRoutines do
    if not Routine.IsEqual(ARoutine) and Routine.XRef.Contains(ARoutine) then
      List.Add(Routine);
end;

function TSnippets.GetRoutines: TRoutineList;
  {Gets list of all snippets in database.
    @return Required list.
  }
begin
  Result := fRoutines;
end;

function TSnippets.InternalAddCategory(const CatName: string;
  const Data: TCategoryData): TCategory;
  {Adds a new category to the user database. Assumes category not already in
  user database.
    @param CatName [in] Name of new category.
    @param Data [in] Properties of new category.
    @return Reference to new category object.
  }
begin
  Result := TCategoryEx.Create(CatName, True, Data);
  fCategories.Add(Result);
end;

function TSnippets.InternalAddRoutine(const RoutineName: string;
  const Data: TRoutineEditData): TRoutine;
  {Adds a new snippet to the user database. Assumes snippet not already in user
  database.
    @param RoutineName [in] Name of new snippet.
    @param Data [in] Properties and references of new snippet.
    @return Reference to new snippet object.
    @except Exception raised if snippet's category does not exist.
  }
var
  Cat: TCategory; // category object containing new snippet
resourcestring
  // Error message
  sCatNotFound = 'Category "%0:s" for new snippet "%1:s" does not exist';
begin
  Result := TRoutineEx.Create(RoutineName, True, Data.Props);
  (Result as TRoutineEx).UpdateRefs(Data.Refs, fRoutines);
  Cat := fCategories.Find(Result.Category);
  if not Assigned(Cat) then
    raise ECodeSnip.CreateFmt(sCatNotFound, [Result.Category, Result.Name]);
  Cat.Routines.Add(Result);
  fRoutines.Add(Result);
end;

procedure TSnippets.InternalDeleteCategory(const Cat: TCategory);
  {Deletes a category from the user database.
    @param Cat [in] Category to delete from database.
  }
begin
  TriggerEvent(evBeforeCategoryDelete, Cat);
  (fCategories as TCategoryListEx).Delete(Cat);
  TriggerEvent(evAfterCategoryDelete);
end;

procedure TSnippets.InternalDeleteRoutine(const Routine: TRoutine);
  {Deletes a snippet from the user database.
    @param Routine [in] Snippet to delete from database.
  }
var
  Cat: TCategory; // category containing snippet
begin
  // Delete from category if found
  Cat := fCategories.Find(Routine.Category);
  if Assigned(Cat) then
    (Cat.Routines as TRoutineListEx).Delete(Routine);
  // Delete from "master" list: this frees Routine
  TriggerEvent(evBeforeRoutineDelete, Routine);
  (fRoutines as TRoutineListEx).Delete(Routine);
  TriggerEvent(evAfterRoutineDelete);
end;

procedure TSnippets.Load;
  {Loads object's data from main and user defined databases.
  }
var
  Factory: ISnippetsFactory;  // object reader uses to create snippets objects
begin
  Clear;
  // Create factory that reader calls into to create category and snippet
  // objects. This is done to keep updating of snippet and categories private
  // to this unit
  Factory := TSnippetsFactory.Create;
  try
    // Load main database: MUST do this first since user database can
    // reference objects in main database
    with TSnippetsIOFactory.CreateMainDBLoader do
      Load(fRoutines, fCategories, Factory);
    // Load any user database
    with TSnippetsIOFactory.CreateUserDBLoader do
      Load(fRoutines, fCategories, Factory);
    fUpdated := False;
  except
    // If an exception occurs clear the database
    Clear;
    raise;
  end;
end;

procedure TSnippets.RemoveChangeEventHandler(const Handler: TNotifyEventInfo);
  {Removes a change event handler from list of listeners.
    @param Handler [in] Handler to remove from list.
  }
begin
  fChangeEvents.RemoveHandler(Handler);
end;

procedure TSnippets.Save;
  {Saves user defined snippets and all categories to user database.
  }
var
  Provider: ISnippetsDataProvider;  // object that supplies info to writer
begin
  // Create object that can provide required information about user database
  Provider := TUserDataProvider.Create(fRoutines, fCategories);
  // Use a writer object to write out the database
  with TSnippetsIOFactory.CreateWriter do
    Write(fRoutines, fCategories, Provider);
  fUpdated := False;
end;

procedure TSnippets.TriggerEvent(const Kind: TSnippetChangeEventKind;
  const Info: TObject);
  {Triggers a change event. Notifies all registered listeners.
    @param Kind [in] Kind of event.
    @param Info [in] Reference to any further information for event. May be nil.
  }
var
  EvtInfo: ISnippetChangeEventInfo; // event information object
begin
  EvtInfo := TEventInfo.Create(Kind, Info);
  fChangeEvents.TriggerEvents(EvtInfo);
end;

function TSnippets.UpdateCategory(const Category: TCategory;
  const Data: TCategoryData): TCategory;
  {Updates a user defined category's properties.
    @param Category [in] Category to be updated. Must be user-defined.
    @param Data [in] Record containing revised data.
    @return Reference to updated category. Will have changed.
  }
var
  SnippetList: TRoutineList;
  Snippet: TRoutine;
  CatName: string;
begin
  TriggerEvent(evChangeBegin);
  try
    SnippetList := TRoutineList.Create;
    try
      for Snippet in Category.Routines do
        SnippetList.Add(Snippet);
      CatName := Category.Category;
      InternalDeleteCategory(Category);
      Result := InternalAddCategory(CatName, Data);
      for Snippet in SnippetList do
        Result.Routines.Add(Snippet);
    finally
      FreeAndNil(SnippetList);
    end;
    TriggerEvent(evCategoryChanged, Result);
  finally
    fUpdated := True;
    TriggerEvent(evChangeEnd);
  end;
end;

function TSnippets.Updated: Boolean;
  {Checks if user database has been updated since last save.
    @return True if database has been updated, False otherwise.
  }
begin
  Result := fUpdated;
end;

function TSnippets.UpdateRoutine(const Routine: TRoutine;
  const Data: TRoutineEditData; const NewName: string): TRoutine;
  {Updates a user defined snippet's properties and references using provided
  data.
    @param Routine [in] Snippet to be updated. Must be user-defined.
    @param Data [in] Record containing revised data.
    @param NewName [in] New name of snippet. Set to '' or Routine.Name if name
      is not to change.
    @return Reference to updated snippet. Will have changed.
  }
var
  RoutineName: string;      // name of snippet
  Dependent: TRoutine;      // loops thru each snippetthat depends on Routine
  Dependents: TRoutineList; // list of dependent snippets
  Referrer: TRoutine;       // loops thru snippets that cross references Routine
  Referrers: TRoutineList;  // list of referencing snippets
resourcestring
  // Error message
  sCantRename = 'Can''t rename snippet %0:s to %1:s: Snippet %1:s already '
    + 'exists in user database';
begin
  Result := Routine;      // keeps compiler happy
  Assert(Routine.UserDefined,
    ClassName + '.UpdateRoutine: Routine is not user-defined');
  TriggerEvent(evChangeBegin);
  try
    // Calculate new name
    if NewName <> '' then
      RoutineName := NewName
    else
      RoutineName := Routine.Name;
    // If name has changed then new name musn't exist in user database
    if not AnsiSameText(RoutineName, Routine.Name) then
      if fRoutines.Find(RoutineName, True) <> nil then
        raise ECodeSnip.CreateFmt(sCantRename, [Routine.Name, RoutineName]);
    // We update by deleting old snippet and inserting new one
    // get lists of snippets that cross reference or depend on this routine
    Dependents := TRoutineList.Create;
    GetDependentList(Routine, Dependents);
    Referrers := TRoutineList.Create;
    GetReferrerList(Routine, Referrers);
    // remove invalid references from referring snippets
    for Referrer in Referrers do
      (Referrer.XRef as TRoutineListEx).Delete(Routine);
    for Dependent in Dependents do
      (Dependent.Depends as TRoutineListEx).Delete(Routine);
    // delete the snippet
    InternalDeleteRoutine(Routine);
    // add new routine
    Result := InternalAddRoutine(RoutineName, Data);
    // add new snippet to referrer list of referring snippets
    for Referrer in Referrers do
      Referrer.XRef.Add(Result);
    for Dependent in Dependents do
      Dependent.Depends.Add(Result);
    TriggerEvent(evRoutineChanged, Result);
  finally
    fUpdated := True;
    TriggerEvent(evChangeEnd);
  end;
end;

{ TSnippets.TEventInfo }

constructor TSnippets.TEventInfo.Create(const Kind: TSnippetChangeEventKind;
  const Info: TObject);
  {Class constructor. Creates an event information object.
    @param Kind [in] Kind of event.
    @param Routine [in] Reference to any snippet affected by event. May be nil
      if event does not affect a snippet.
  }
begin
  inherited Create;
  fKind := Kind;
  fInfo := Info;
end;

function TSnippets.TEventInfo.GetInfo: TObject;
  {Gets additional information about event.
    @return Object that provides required information.
  }
begin
  Result := fInfo;
end;

function TSnippets.TEventInfo.GetKind: TSnippetChangeEventKind;
  {Gets kind (type) of event.
    @return Event kind.
  }
begin
  Result := fKind;
end;

{ TRoutine }

function TRoutine.CanCompile: Boolean;
  {Checks if snippet can be compiled.
    @return True if compilation supported and False if not.
  }
begin
  Result := Kind <> skFreeform;
end;

constructor TRoutine.Create(const Name: string; const UserDefined: Boolean;
  const Props: TRoutineData);
  {Class contructor. Sets up snippet object with given property values.
    @param Name [in] Name of snippet.
    @param UserDefined [in] Indicates if this is a user defined snippet.
    @param Props [in] Values of various snippet properties.
  }
begin
  Assert(ClassType <> TRoutine,
    ClassName + '.Create: must only be called from descendants.');
  inherited Create;
  // Record simple property values
  SetName(Name);
  SetProps(Props);
  // Create string list to store required units
  fUnits := TStringList.Create;
  // Create routine lists for Depends and XRef properties
  fDepends := TRoutineListEx.Create;
  fXRef := TRoutineListEx.Create;
  // The following properties added to support user defined snippets
  fUserDefined := UserDefined;
end;

destructor TRoutine.Destroy;
  {Class destructor. Tears down object.
  }
begin
  FreeAndNil(fXRef);
  FreeAndNil(fDepends);
  FreeAndNil(fUnits);
  fExtra := nil;
  inherited;
end;

function TRoutine.GetID: TSnippetID;
  {Gets snippet's unique ID.
    @return Required ID.
  }
begin
  Result := TSnippetID.Create(fName, fUserDefined);
end;

function TRoutine.IsEqual(const Routine: TRoutine): Boolean;
  {Checks if this snippet is same as another snippet. Snippets are considered
  equal if they have the same name and come from same database.
    @param Routine [in] Snippet being compared.
    @return True if snippets are equal, False if not.
  }
begin
  Result := Routine.ID = Self.ID;
end;

procedure TRoutine.SetName(const Name: string);
  {Sets Name property.
    @param Name [in] New name.
  }
begin
  fName := Name;
end;

procedure TRoutine.SetProps(const Data: TRoutineData);
  {Sets snippet's properties.
    @param Data [in] Record containing property values.
  }
begin
  fCategory := Data.Cat;
  fKind := Data.Kind;
  fDescription := Data.Desc;
  fSourceCode := AdjustLineBreaks(Data.SourceCode); // ensure EOLs are CRLF
  fExtra := TActiveTextFactory.CloneActiveText(Data.Extra);
  fCompatibility := Data.CompilerResults;
end;

{ TRoutineEx }

function TRoutineEx.GetEditData: TRoutineEditData;
  {Gets details of all editable data of snippet.
    @return Required editable properties and references.
  }
begin
  Result.Props := GetProps;
  Result.Refs := GetReferences;
end;

function TRoutineEx.GetProps: TRoutineData;
  {Gets details of snippet's properties.
    @return Record containing property values.
  }
begin
  Result.Cat := Category;
  Result.Kind := Kind;
  Result.Desc := Description;
  Result.SourceCode := SourceCode;
  Result.Extra := TActiveTextFactory.CloneActiveText(Extra);
  Result.CompilerResults := Compatibility;
end;

function TRoutineEx.GetReferences: TRoutineReferences;
  {Gets details of snippet's references.
    @return Information sufficient to define references.
  }
begin
  Result.Units := TIStringList.Create(Units);
  Result.Depends := TSnippetIDListEx.Create(Depends);
  Result.XRef := TSnippetIDListEx.Create(XRef);
end;

procedure TRoutineEx.Update(const Data: TRoutineEditData;
  const AllRoutines: TRoutineList);
  {Updates snippet's properties and references.
    @param Data [in] New property values and references.
    @param AllRoutines [in] List of all snippets in database.
  }
begin
  SetProps(Data.Props);
  UpdateRefs(Data.Refs, AllRoutines);
end;

procedure TRoutineEx.UpdateRefs(const Refs: TRoutineReferences;
  const AllRoutines: TRoutineList);
  {Updates a snippet's references.
    @param Refs [in] Stores all snippet's references (XRef, Depends and
      Units).
    @param AllRoutines [in] List of all snippets in database.
  }

  // ---------------------------------------------------------------------------
  procedure BuildRoutineList(const SL: TRoutineList;
    const IDList: ISnippetIDList);
    {Creates a snippets list from a snippets ID list. Looks up snippets in list
    of all snippets in database. Any snippets in ID list that do not exist in
    database are ignored.
      @param SL [in] Snippets list object to be updated.
      @param IDList [in] Snippets ID list that provides information used to
        create snippets list.
    }
  var
    ID: TSnippetID;     // refers to each ID in ID list
    Routine: TRoutine;  // references each snippet identified by ID
  begin
    SL.Clear;
    for ID in IDList do
    begin
      Routine := AllRoutines.Find(ID.Name, ID.UserDefined);
      if Assigned(Routine) then
        SL.Add(Routine);
    end;
  end;
  // ---------------------------------------------------------------------------

begin
  Refs.Units.CopyTo(Self.Units, True);            // copy units
  BuildRoutineList(Self.Depends, Refs.Depends);   // build Depends list
  BuildRoutineList(Self.XRef, Refs.XRef);         // build XRef list
end;

{ TRoutineList }

function TRoutineList.Add(const Routine: TRoutine): Integer;
  {Adds new snippet to the list, maintaining list in alphabetical order.
    @param Routine [in] Snippet being added.
    @return Index where item was inserted in list
    @except Raised if duplicate snippet added to list.
  }
var
  Idx: Integer; // loops thru list
  Cmp: Integer; // result of comparison of snippet names
begin
  // Assume adding to end of list
  Result := Count;
  // Loop thru existing items searching for location to insert
  for Idx := 0 to Pred(Count) do
  begin
    // compare new item to current item
    Cmp := CompareIDs(Routine.ID, Items[Idx].ID);
    if Cmp = 0 then
      // don't allow duplicates
      raise EBug.CreateFmt(
        ClassName + '.Add: Duplicate snippet name (%s) in same database',
        [Routine.Name]
      );
    if Cmp < 0 then
    begin
      // current item is greater than new one: insert before it
      Result := Idx;
      Break;
    end;
  end;
  // add the new item
  fList.Insert(Result, Routine);
end;

procedure TRoutineList.Assign(const SrcList: TRoutineList);
  {Sets this list to be same as another list. List items are referenced, not
  copied.
    @param SrcList [in] List of snippets to be assigned.
  }
var
  Idx: Integer; // loops thru source list
begin
  Assert(not fList.OwnsObjects,
    ClassName + '.Assign: can''t assign to master list');
  Self.Clear;
  if Assigned(SrcList) then
  begin
    for Idx := 0 to Pred(SrcList.Count) do
      Self.Add(SrcList[Idx]);
  end;
end;

procedure TRoutineList.Clear;
  {Clears the list.
  }
begin
  fList.Clear;
end;

function TRoutineList.CompareIDs(const SID1, SID2: TSnippetID): Integer;
  {Compares IDS of two snippets.
    @param SID1 [in] First ID to be compared.
    @param SID2 [in] Second ID to be compared.
    @return 0 if IDs are the same, -ve if SID1 < SID2 and +ve if
      SID1 > SID2.
  }
begin
  Result := SID1.Compare(SID2);
end;

function TRoutineList.Contains(const Routine: TRoutine): Boolean;
  {Checks whether list contains a specified snippet.
    @param Routine [in] Required snippet.
    @return True if snippet is in list, False otherwise.
  }
begin
  Result := fList.Contains(Routine);
end;

function TRoutineList.ContainsKinds(const Kinds: TSnippetKinds): Boolean;
  {Checks if the list contains specified kinds of snippets.
    @param Kinds [in] Set of kinds to test for.
    @return True if list contains at least one snippet of any of the specified
      kinds.
  }
var
  Snippet: TRoutine;  // reference to all snippets in list
begin
  Result := False;
  for Snippet in Self do
    if Snippet.Kind in Kinds then
    begin
      Result := True;
      Break;
    end;
end;

function TRoutineList.Count(const UserDefined: Boolean): Integer;
  {Counts number of snippets in list that are either from or not from user
  defined database.
    @param UserDefined [in] Flags whether to count snippets in user database
      (True) or in main database (False).
    @return Number of snippets in specified database.
  }
var
  Routine: TRoutine;  // refers to all snippets in list
begin
  Result := 0;
  for Routine in Self do
    if Routine.UserDefined = UserDefined then
      Inc(Result);
end;

function TRoutineList.Count: Integer;
  {Counts number of snippets in list.
    @return Number of snippets in list.
  }
begin
  Result := fList.Count;
end;

constructor TRoutineList.Create(const OwnsObjects: Boolean = False);
  {Class constructor. Creates a new empty list.
    @param OwnsObjects [in] Specifies whether list owns the snippet objects it
      contains. If True the snippets are freed when deleted from list.
  }
begin
  inherited Create;
  fList := TObjectListEx.Create(OwnsObjects);
end;

destructor TRoutineList.Destroy;
  {Class destructor. Tears down object.
  }
begin
  FreeAndNil(fList);  // destroys owned snippets if OwnsObjects=True
  inherited;
end;

function TRoutineList.Find(const RoutineName: string;
  const UserDefined: Boolean; out Index: Integer): Boolean;
  {Finds a snippet in the list that has a specified name and user defined
  property. Uses a binary search.
    @param RoutineName [in] Name of snippet to be found.
    @param UserDefined [in] Whether required snippet is user defined or not.
    @param Index [out] Index of required snippet in list. Valid only if
      method returns True.
    @return True if snippet found, False if not.
  }
var
  Low, High: Integer;   // low and high bounds of search
  Cur: Integer;         // current item to be tested
  Cmp: Integer;         // result of comparing two items
  SearchID: TSnippetID; // ID of snippet being search for
begin
  // Uses binary search: based on TStringList.Find from Delphi Classes unit
  // Initialise
  Result := False;
  Low := 0;
  High := Count - 1;
  SearchID := TSnippetID.Create(RoutineName, UserDefined);
  // Perform binary search
  while Low <= High do
  begin
    // Choose item to be compared: mid point of range
    Cur := (Low + High) shr 1;
    // Compare chosen
    Cmp := CompareIDs(Items[Cur].ID, SearchID);
    if Cmp < 0 then
      // Current item < required: search above current item
      Low := Cur + 1
    else
    begin
      // Current item >= required: search below current item
      High := Cur - 1;
      if Cmp = 0 then
      begin
        // We found it: set Low to Cur because Cur > High => loop will terminate
        Result := True;
        Low := Cur;
      end;
    end;
  end;
  // Set index (Low = Cur if found)
  Index := Low;
end;

function TRoutineList.Find(const RoutineName: string;
  const UserDefined: Boolean): TRoutine;
  {Finds a named snippet in list with a matching user defined property.
    @param RoutineName [in] Name of required snippet.
    @param UserDefined [in] Flag that determines if we are looking for a
      user defined snippet or one from main database.
    @return Reference to object representing snippet in list or nil if not
      in list.
  }
var
  Idx: Integer; // index of snippet name in list
begin
  if Find(RoutineName, UserDefined, Idx) then
    Result := Items[Idx]
  else
    Result := nil;
end;

function TRoutineList.GetEnumerator: TEnumerator;
  {Gets an intialised snippet list enumerator.
    @return Required enumerator.
  }
begin
  Result := TEnumerator.Create(Self);
end;

function TRoutineList.GetItem(Idx: Integer): TRoutine;
  {Read accessor for Items property.
    @param Idx [in] Index of required snippet in list.
    @return Snippet at specified index in list.
  }
begin
  Result := fList[Idx] as TRoutine;
end;

function TRoutineList.IsEqual(const AList: TRoutineList): Boolean;
  {Checks if this list contains same snippets as another list.
    @param AList [in] List of snippets to compare.
    @return True if lists are same, False if not.
  }
var
  Idx: Integer; // loops thru all snippets in list
begin
  // To be same comparison list must exist and have same number of snippets
  Result := Assigned(AList) and (Self.Count = AList.Count);
  if Result then
  begin
    // Same number of snippets: scan list checking routine names same. We can
    // rely on items being in same order since lists are sorted
    for Idx := 0 to Pred(Self.Count) do
    begin
      if not Self[Idx].IsEqual(AList[Idx]) then
      begin
        Result := False;
        Break;
      end;
    end;
  end;
end;

{ TRoutineList.TEnumerator }

constructor TRoutineList.TEnumerator.Create(const RL: TRoutineList);
  {Class constructor. Sets up and initialises enumeration.
    @param RL [in] Reference to snippet list object to be enumerated.
  }
begin
  inherited Create;
  fRoutineList := RL;
  fIndex := -1;
end;

function TRoutineList.TEnumerator.GetCurrent: TRoutine;
  {Gets current snippet in enumeration. Error if at end of enumeration.
    @return Current snippet.
  }
begin
  Result := fRoutineList[fIndex];
end;

function TRoutineList.TEnumerator.MoveNext: Boolean;
  {Moves to next item in enumeration.
    @return True if there is a next item, False if enumeration
      completed.
  }
begin
  Result := fIndex < Pred(fRoutineList.Count);
  if Result then
    Inc(fIndex);
end;

{ TRoutineListEx }

function TRoutineListEx.Add(const Routine: TRoutine): Integer;
  {Adds a snippet to list. Prevents TTempRoutine instances from being added.
    @param Routine [in] Snippet to be added.
    @return Index where snippet was added to list.
    @except EBug raised if Routine is a TTempRoutine instance.
  }
begin
  if Routine is TTempRoutine then
    // don't allow temp routines to be added to list
    raise EBug.CreateFmt(
      ClassName + '.Add: Can''t add temporary snippets to database (%s)',
      [Routine.Name]
    );
  Result := inherited Add(Routine);
end;

procedure TRoutineListEx.Delete(const Routine: TRoutine);
  {Deletes a snippet from list.
    @param Routine [in] Snippet to be deleted. No action taken if snippet not in
      list.
  }
var
  Idx: Integer; // index of snippet in list.
begin
  Idx := fList.IndexOf(Routine);
  if Idx = -1 then
    Exit;
  fList.Delete(Idx);  // this frees snippet if list owns objects
end;

{ TCategory }

constructor TCategory.Create(const CatID: string; const UserDefined: Boolean;
  const Data: TCategoryData);
  {Class contructor. Sets up category object with given property values.
    @param Data [in] Contains required property values.
  }
begin
  Assert(ClassType <> TCategory,
    ClassName + '.Create: must only be called from descendants.');
  inherited Create;
  fCategory := CatID;
  fDescription := Data.Desc;
  fUserDefined := UserDefined;
  // Create list to store snippets in category
  fRoutines := TRoutineListEx.Create;
end;

destructor TCategory.Destroy;
  {Class destructor. Tears down object.
  }
begin
  FreeAndNil(fRoutines);
  inherited;
end;

function TCategory.IsEqual(const Cat: TCategory): Boolean;
  {Checks if this category is same as another category. Categories are
  considered equal if they have the same name.
    @param Cat [in] Category being compared.
    @return True if categories are equal, False if not.
  }
begin
  Result := AnsiSameText(Self.Category, Cat.Category);
end;

{ TCategoryEx }

function TCategoryEx.GetEditData: TCategoryData;
  {Gets details of all editable data of category.
    @return Required editable data.
  }
begin
  Result.Desc := Self.Description;
end;

{ TCategoryList }

function TCategoryList.Add(const Category: TCategory): Integer;
  {Adds new category to list.
    @param Category [in] Category to be added.
    @return Index where category inserted in list.
  }
begin
  Assert(not fList.Contains(Category),
    ClassName + '.Add: Category already in list');
  Result := fList.Add(Category);
end;

procedure TCategoryList.Clear;
  {Clears the list.
  }
begin
  fList.Clear;
end;

function TCategoryList.Contains(const Category: TCategory): Boolean;
  {Checks if a category is in list. Checks object reference.
    @param Category [in] Category to be checked.
    @return True if category object is in list.
  }
begin
  Result := fList.Contains(Category);
end;

constructor TCategoryList.Create(const OwnsObjects: Boolean);
  {Class constructor. Creates a new empty list.
    @param OwnsObjects [in] Specifies whether list owns the category objects it
      contains. If True the categories are freed when deleted from list.
  }
begin
  inherited Create;
  fList := TObjectListEx.Create(OwnsObjects);
end;

destructor TCategoryList.Destroy;
  {Class destructor. Tears down object.
  }
begin
  FreeAndNil(fList);
  inherited;
end;

function TCategoryList.Find(const CatName: string): TCategory;
  {Finds a named category in list.
    @param CatName [in] Name of required category.
    @return Reference to object representing category in list or nil if not in
      list.
  }
var
  Idx: Integer;   // loops thru categories
begin
  Result := nil;
  for Idx := 0 to Pred(Count) do
  begin
    if AnsiSameText(CatName, Items[Idx].Category) then
    begin
      Result := Items[Idx];
      Break;
    end;
  end;
end;

function TCategoryList.GetCount: Integer;
  {Read accessor for Count property.
    @return Number of categories in list.
  }
begin
  Result := fList.Count;
end;

function TCategoryList.GetEnumerator: TEnumerator;
  {Gets an intialised category list enumerator.
    @return Required enumerator.
  }
begin
  Result := TEnumerator.Create(Self);
end;

function TCategoryList.GetItem(Idx: Integer): TCategory;
  {Read accessor for Items property.
    @param Idx [in] Index of required category in list.
    @return Category at specified index in list.
  }
begin
  Result := fList[Idx] as TCategory;
end;

{ TCategoryList.TEnumerator }

constructor TCategoryList.TEnumerator.Create(const CL: TCategoryList);
  {Class constructor. Sets up and initialises enumeration.
    @param CL [in] Reference to object to be enumerated.
  }
begin
  inherited Create;
  fCategoryList := CL;
  fIndex := -1;
end;

function TCategoryList.TEnumerator.GetCurrent: TCategory;
  {Gets current category in enumeration. Error if at end of enumeration.
    @return Current category.
  }
begin
  Result := fCategoryList[fIndex];
end;

function TCategoryList.TEnumerator.MoveNext: Boolean;
  {Moves to next item in enumeration.
    @return True if there is a next item, False if enumeration completed.
  }
begin
  Result := fIndex < Pred(fCategoryList.Count);
  if Result then
    Inc(fIndex);
end;

{ TCategoryListEx }

procedure TCategoryListEx.Delete(const Category: TCategory);
  {Deletes a category from the list.
    @param Category [in] Category to be deleted.
  }
var
  Idx: Integer; // index of snippet in list.
begin
  Idx := fList.IndexOf(Category);
  if Idx = -1 then
    Exit;
  fList.Delete(Idx);  // this frees category if list owns objects
end;

{ TSnippetsFactory }

function TSnippetsFactory.CreateCategory(const CatID: string;
  const UserDefined: Boolean; const Data: TCategoryData): TCategory;
  {Creates a new category object.
    @param CatID [in] ID (name) of new category. Must be unique.
    @param UserDefined [in] True if category is user defined, False if not.
    @param Data [in] Record describing category's properties.
    @return Instance of new category object.
  }
begin
  Result := TCategoryEx.Create(CatID, UserDefined, Data);
end;

function TSnippetsFactory.CreateRoutine(const Name: string;
  const UserDefined: Boolean; const Props: TRoutineData): TRoutine;
  {Creates a new snippet object.
    @param Name [in] Name of new snippet. Must not exist in database specified
      by UserDefined parameter.
    @param UserDefined [in] True if snippet is user defined, False if not.
    @param Props [in] Record describing snippet's properties.
    @return Instance of new snippet with no references.
  }
begin
  Result := TRoutineEx.Create(Name, UserDefined, Props);
end;

{ TUserDataProvider }

constructor TUserDataProvider.Create(const Routines: TRoutineList;
  const Categories: TCategoryList);
  {Class constructor. Records list of all snippets and categories in both
  databases.
    @param Routines [in] List of all snippets in whole database.
    @param Categories [in] List of all categories in whole database.
  }
begin
  inherited Create;
  fRoutines := Routines;
  fCategories := Categories;
end;

function TUserDataProvider.GetCategoryProps(
  const Cat: TCategory): TCategoryData;
  {Retrieves all the properties of a category.
    @param Cat [in] Category for which data is requested.
    @return Record containing property data.
  }
begin
  Result.Desc := Cat.Description;
end;

function TUserDataProvider.GetCategoryRoutines(
  const Cat: TCategory): IStringList;
  {Retrieves names of all user-defined snippets that belong to a category.
    @param Cat [in] Category for which snippet names are requested.
    @return Required list of snippet names.
  }
var
  Routine: TRoutine;  // references each snippet in category
begin
  Result := TIStringList.Create;
  for Routine in Cat.Routines do
    if Routine.UserDefined then
      Result.Add(Routine.Name);
end;

function TUserDataProvider.GetRoutineProps(
  const Routine: TRoutine): TRoutineData;
  {Retrieves all the properties of a snippet.
    @param Routine [in] Snippet for which data is requested.
    @return Record containing property data.
  }
begin
  Result := (Routine as TRoutineEx).GetProps;
end;

function TUserDataProvider.GetRoutineRefs(
  const Routine: TRoutine): TRoutineReferences;
  {Retrieves information about all the references of a snippet.
    @param Routine [in] Snippet for which information is requested.
    @return Record containing references.
  }
begin
  Result := (Routine as TRoutineEx).GetReferences;
end;

{ TRoutineData }

procedure TRoutineData.Assign(const Src: TRoutineData);
  {Sets this record to be a copy of another record.
    @param Src [in] Record to be copied.
  }
begin
  Kind := Src.Kind;
  Cat := Src.Cat;
  Desc := Src.Desc;
  SourceCode := Src.SourceCode;
  // we use cloning for Extra below because it deals uccessfully with both
  // Self.Extra = nil and Src.Extra = nil
  Extra := TActiveTextFactory.CloneActiveText(Src.Extra);
  CompilerResults := Src.CompilerResults;
end;

procedure TRoutineData.Init;
  {Initialises record by setting default values for fields.
  }
var
  CompID: TCompilerID;  // loops thru compiler IDs
begin
  Kind := skFreeform;
  Cat := '';
  Desc := '';
  SourceCode := '';
  Extra := TActiveTextFactory.CreateActiveText;
  for CompID := Low(TCompilerID) to High(TCompilerID) do
    CompilerResults[CompID] := crQuery;
end;

{ TRoutineReferences }

procedure TRoutineReferences.Assign(const Src: TRoutineReferences);
  {Sets this record to be a copy of another record.
    @param Src [in] Record to be copied.
  }
begin
  Init;
  (Units as IAssignable).Assign(Src.Units);
  (Depends as IAssignable).Assign(Src.Depends);
  (XRef as IAssignable).Assign(Src.XRef);
end;

procedure TRoutineReferences.Init;
  {Initialises record by creating objects stored in fields.
  }
begin
  Units := TIStringList.Create;
  Depends := TSnippetIDList.Create;
  XRef := TSnippetIDList.Create;
end;

{ TRoutineEditData }

procedure TRoutineEditData.Assign(const Src: TRoutineEditData);
  {Sets this record to be a copy of another record.
    @param Src [in] Record to be copied.
  }
begin
  Props.Assign(Src.Props);
  Refs.Assign(Src.Refs);
end;

procedure TRoutineEditData.Init;
  {Initialises record by creating default values and field objects.
  }
begin
  Props.Init;
  Refs.Init;
end;

{ TRoutineInfo }

procedure TRoutineInfo.Assign(const Src: TRoutineInfo);
  {Sets this record's fields to be same as another TRoutineInfo record.
  Object fields are copied appropriately.
    @param Src [in] Record containing fields to be copied.
  }
begin
  Name := Src.Name;
  Data.Assign(Src.Data);
end;

procedure TRoutineInfo.Init;
  {Initialises record to nul values.
  }
begin
  Name := '';
  Data.Init;
end;

{ TCategoryData }

procedure TCategoryData.Assign(const Src: TCategoryData);
  {Sets this record's fields to be same as another TCategoryData record.
    @param Src [in] Record containing fields to be copied.
  }
begin
  Desc := Src.Desc;
end;

procedure TCategoryData.Init;
  {Initialises record to nul values.
  }
begin
  Desc := '';
end;

{ TCategoryInfo }

procedure TCategoryInfo.Assign(const Src: TCategoryInfo);
  {Sets this record's fields to be same as another TCategoryInfo record.
    @param Src [in] Record containing fields to be copied.
  }
begin
  Name := Src.Name;
  Data.Assign(Src.Data);
end;

procedure TCategoryInfo.Init;
  {Initialises record to nul values.
  }
begin
  Name := '';
  Data.Init;
end;

{ TSnippetIDListEx }

constructor TSnippetIDListEx.Create(const Routines: TRoutineList);
  {Class constructor overload that creates a snippets ID list from a
  TRoutineList object.
    @param Routines [in] List of snippets objects for which ID list is
      required.
  }
var
  Snippet: TRoutine;  // references each snippet in list
begin
  inherited Create;
  for Snippet in Routines do
    Add(Snippet.ID);
end;

initialization


finalization

// Free the singleton
PvtSnippets := nil;

end.