CodeSnip Old Code (SVN)

{
 * UQuery.pas
 *
 * Defines a singleton object that encapsulates a query on the code snippets
 * database.
 *
 * $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 UQuery.pas
 *
 * The Initial Developer of the Original Code is Peter Johnson
 * (http://www.delphidabbler.com/).
 *
 * Portions created by the Initial Developer are Copyright (C) 2007-2009 Peter
 * Johnson. All Rights Reserved.
 *
 * Contributor(s)
 *   NONE
 *
 * ***** END LICENSE BLOCK *****
}


unit UQuery;


interface


uses
  // Project
  USearch, USnippets;


type

  {
  IQuery:
    Interface to object that encapsulates a query on the code snippets database.
    It enables a search to be run against the database and provides access to
    the selected routines.
  }
  IQuery = interface(IInterface)
    ['{10998D72-CD5D-482B-9626-D771A50C53BA}']
    function ApplySearch(const Search: ISearch): Boolean;
      {Runs query by applying a search to the whole database. If search succeeds
      matching routines and search are stored in query's Selection and Search
      properties. If search fails Selection and Search are left unchanged.
        @param Search [in] Search to apply.
        @return True if search succeeds and False if it fails.
      }
    procedure Reset;
      {Resets query. Selection property is set to all routines in database and
      Search property is set to nul search.
      }
    function Refresh: Boolean;
      {Re-applies the current search if one exists.
        @return True if search was re-applied, False if there was no search to
          apply.
      }
    function GetCurrentSearch: ISearch;
      {Gets value of CurrentSearch property.
        @return Search object used to generate current search.
      }
    function GetSelection: TRoutineList;
      {Gets value of Selection property.
        @return List of routines matching current query.
      }
    procedure GetCatSelection(const Cat: TCategory;
      const Routines: TRoutineList);
      {Provides list of routines selected by last search that are in a specified
      category.
        @param Cat [in] Reference to required category.
        @param Routines [in] Object to receive routine list. List is emptied
          before routines are copied in.
      }
    property CurrentSearch: ISearch read GetCurrentSearch;
      {Reference to search object used to generate current query}
    property Selection: TRoutineList read GetSelection;
      {List of routines that match current query. This records all routines in
      database if there is no search}
  end;


function Query: IQuery;
  {Returns singleton instance of object that encapsulates a query on the
  snippets database.
    @return Singleton object.
  }


implementation


uses
  // Delphi
  SysUtils,
  // Project
  UBaseObjects;


type

  {
  TQuery:
    Class that encapsulates a query on the code snippets database. It enables a
    search to be run against the database and makes the found routines
    available. Must only be instantiated once as a singleton.
  }
  TQuery = class(TNoPublicConstructIntfObject,
    IQuery
  )
  strict private
    var
      fSelection: TRoutineList;   // List of routines selected by current query
      fSearch: ISearch;           // Search object used by current query
    class var
      fInstance: IQuery;          // Singleton object instance of this class
    class function GetInstance: IQuery; static;
      {Gets singleton instance of class, creating it if necessary
        @return Singleton instance.
      }
  protected // do not make strict
    { IQuery methods }
    function ApplySearch(const Search: ISearch): Boolean;
      {Runs query by applying a search to the whole database. If search succeeds
      matching routines and search are stored in query's Selection and Search
      properties. If search fails Selection and Search are left unchanged.
        @param Search [in] Search to apply.
        @return True if search succeeds and False if it fails.
      }
    function Refresh: Boolean;
      {Re-applies the current search if one exists.
        @return True if search was re-applied, False if there was no search to
          apply.
      }
    procedure Reset;
      {Resets query. Selection property is set to all routines in database and
      Search property is set to nul search.
      }
    function GetCurrentSearch: ISearch;
      {Gets reference to current search object.
        @return Required search object.
      }
    function GetSelection: TRoutineList;
      {Gets reference to list of routines selected by last search.
        @return Reference to required list of routines.
      }
    procedure GetCatSelection(const Cat: TCategory;
      const Routines: TRoutineList);
      {Provides list of routines selected by last search that are in a specified
      category.
        @param Cat [in] Reference to required category.
        @param Routines [in] Object to receive routine list. List is emptied
          before routines are copied in.
      }
  strict protected
    constructor InternalCreate;
      {Internal class constructor. Sets up object with all routines in database
      selected.
      }
  public
    destructor Destroy; override;
      {Class destructor. Tears down object.
      }
    class property Instance: IQuery read GetInstance;
  end;

function Query: IQuery;
  {Returns singleton instance of object that encapsulates a query on the
  snippets database.
    @return Singleton object.
  }
begin
  Result := TQuery.Instance;
end;

{ TQuery }

function TQuery.ApplySearch(const Search: ISearch): Boolean;
  {Runs query by applying a search to the whole database. If search succeeds
  matching routines and search are stored in query's Selection and Search
  properties. If search fails Selection and Search are left unchanged.
    @param Search [in] Search to apply.
    @return True if search succeeds and False if it fails.
  }
var
  FoundList: TRoutineList;  // list receives found routines
begin
  Assert(Assigned(Search), ClassName + '.ApplySearch: Search is nil');
  FoundList := TRoutineList.Create;
  try
    // Get list of routines that match search
    // if there are no routines found we leave current selection alone
    Result := (Search as ISearch).Execute(Snippets.Routines, FoundList);
    if Result then
    begin
      // Search succeeded: record search and list of routines
      fSearch := Search;
      fSelection.Assign(FoundList);
    end;
  finally
    FreeAndNil(FoundList);
  end;
end;

destructor TQuery.Destroy;
  {Class destructor. Tears down object.
  }
begin
  FreeAndNil(fSelection);
  fSearch := nil;
  inherited;
end;

procedure TQuery.GetCatSelection(const Cat: TCategory;
  const Routines: TRoutineList);
  {Provides list of routines selected by last search that are in a specified
  category.
    @param Cat [in] Reference to required category.
    @param Routines [in] Object to receive routine list. List is emptied before
      routines are copied in.
  }
var
  Idx: Integer; // Loops thru all routines in selection
begin
  Routines.Clear;
  for Idx := 0 to Pred(fSelection.Count) do
  begin
    if Cat.Routines.Contains(fSelection[Idx]) then
      Routines.Add(fSelection[Idx]);
  end;
end;

function TQuery.GetCurrentSearch: ISearch;
  {Gets reference to current search object.
    @return Required search object.
  }
begin
  Result := fSearch;
end;

class function TQuery.GetInstance: IQuery;
  {Gets singleton instance of class, creating it if necessary
    @return Singleton instance.
  }
begin
  if not Assigned(fInstance) then
    fInstance := TQuery.InternalCreate; // "TQuery" reference required here
  Result := fInstance;
end;

function TQuery.GetSelection: TRoutineList;
  {Gets reference to list of routines selected by last search.
    @return Reference to required list of routines.
  }
begin
  Result := fSelection;
end;

constructor TQuery.InternalCreate;
  {Internal class constructor. Sets up object with all routines in database
  selected. Must only be called once.
  }
begin
  Assert(not Assigned(fInstance),
    ClassName + '.InternalCreate: Must only call once - singleton object');
  inherited InternalCreate;
  fSelection := TRoutineList.Create;
  Reset;
end;

function TQuery.Refresh: Boolean;
  {Re-applies the current search if one exists.
    @return True if search was re-applied, False if there was no search to
      apply.
  }
begin
  if Assigned(fSearch) then
    Result := ApplySearch(fSearch)
  else
    Result := False;
end;

procedure TQuery.Reset;
  {Resets query. Selection property is set to all routines in database and
  Search property is set to nul search.
  }
begin
  fSelection.Assign(Snippets.Routines);
  fSearch := TSearchFactory.CreateNulSearch;
end;

end.