Project Line Counter Add-In v2.10 for VS.NET and VC6

///////////////////////////////////////////////////////////////////////////////
// $Workfile: WWhizInterface.h $
// $Archive: /WorkspaceWhiz/Src/Shared/WWhizInterface.h $
// $Date:: 3/27/00 2:08p   $ $Revision:: 11   $ $Author: Jjensen $
//
// This source file [WWhizInterface.h]
// is Copyright 1997-2000 by Joshua C. Jensen.
//
// Unauthorized use of this source file, by modification, copying, or
// distribution is strictly prohibited unless prior consent has
// been given by Joshua C. Jensen.
///////////////////////////////////////////////////////////////////////////////
#pragma once

class WWhizReg;
class WWhizProjectList;
class WWhizProject;
class WWhizFileList;
class WWhizFile;
class WWhizTagList;
class WWhizTag;
class WWhizConfig;

/**
	This is the base class for several Workspace Whiz! objects that allows
	reference counting.  It should look fairly similar to COM's IUnknown.
**/
class WWhizBase
{
public:
	/**
		@return	Returns the current reference count of the object.
	**/
	virtual UINT GetRefCount() = 0;

	/**
		Increases the object's reference count by one.
		@return Returns the current reference count of the object.
	**/
	virtual UINT AddRef() = 0;

	/**
		Decreases the object's reference count by one.
		@return Returns the current reference count of the object.
	**/
    virtual UINT Release() = 0;
};


/**
	The interface to the attributes of a tag.  This class represents a single
	tag.
**/
class WWhizTag
{
public:
	/**
		The various types a tag can be.
	**/
	enum Type
	{
		CLASS,			//!< A class definition.
		DEFINE,			//!< A #define statement.
		ENUM,			//!< An enumeration.
		ENUMMEMBER,		//!< An enumeration's member.
		FUNCTION,		//!< A function.
		MEMBER,			//!< A class or structure member.
		NAMESPACE,		//!< A namespace.
		STRUCTURE,		//!< A structure definition.
		TYPEDEF,		//!< A typedef definition.
		UNION,			//!< A union.
		VARIABLE,		//!< A variable.
		LAST_TYPE,
	};

	/**
		@return Returns the type of the tag.
	**/
	virtual Type GetType(void) const = 0;

	/**
		To facilitate faster tag lookups, every tag has a "short" identifier
		associated with it.  The short identifier is all lowercase and only
		contains alphanumeric characters.  Underscores are not included.
		Do not use GetShortIdent() for the display of the tag name.  Instead,
		use GetIdent().
		@return Returns the alphanumeric "short" name for the tag.
	**/
	virtual const CString& GetShortIdent(void) const = 0;

	/**
		@return Returns the true tag name, case-sensitive.
	**/
	virtual const CString& GetIdent(void) const = 0;

	/**
		@return Returns the filename the tag resides within.
	**/
	virtual const CString& GetFilename(void) const = 0;

	/**
		@return Returns the regular expression used to search for the tag.
	**/
	virtual const CString& GetSearchString(void) const = 0;

	/**
		To facilitate faster tag lookups, every parent tag has a "short"
		identifier associated with it.  The short identifier is all lowercase
		and only contains alphanumeric characters.  Underscores are not
		included.  Do not use GetShortParentIdent() for the display of the
		parent tag name.  Instead, use GetParentIdent().
		@return Returns the alphanumeric "short" name for the parent tag.
	**/
	virtual const CString& GetShortParentIdent(void) const = 0;

	/**
		@return Returns the true parent tag name, case-sensitive.
	**/
	virtual const CString& GetParentIdent(void) const = 0;

	/**
		@return For tags of type Type::DEFINE, returns the line number
			the #define exists at.  Type::DEFINE tags do not have search
			strings.
	**/
	virtual int GetLineNumber(void) const = 0;

	/**
		@return Returns the next matching tag, based on search criteria
			specified through the WWhizInterface::MatchTag() function.
	**/
	virtual WWhizTag* GetMatchNext(void) const = 0;

	/**
		@return Returns the previous matching tag, based on search criteria
			specified through the WWhizInterface::MatchTag() function.
	**/
	virtual WWhizTag* GetMatchPrev(void) const = 0;
};


/**
	This is the master control mechanism for anything residing in the
	WWhizInterface module.  All facilities for project information, file
	lists, and tag lists are accessible from this interface.

	Note: Any filename passed to any WWhizInterface function is passed
	through ResolveFilename().
**/
class WWhizInterface
{
public:
	/**
		For every file parsed during the creation of the tags,
		TagCallbackInfo is filled in and passed to an application-specified
		callback routine.
	**/
	struct TagCallbackInfo
	{
		void* m_userData;			//!< User data specified
		int m_curFile;				//!< The current file number being processed.
		int m_numFiles;				//!< The number of files to be processed.
		LPCTSTR m_curFilename;		//!< The filename of the file currently being processed.
	};

	/**
		The definition of the callback called from the tag refresh.
	**/
	typedef void (*TagRefreshCallback)(const TagCallbackInfo& info);

	/**
		Initializes the WWhizInterface.
	**/
	virtual void Initialize() = 0;

	///////////////////////////////////////////////////////////////////////////
	// File support
	///////////////////////////////////////////////////////////////////////////
	/**
		@return Returns the list of projects considered by WWhizInterface.
			The list includes the projects from the open workspace and any
			other application-added projects, particularly through the
			registration module's ExtraFiles interface.
	**/
	virtual WWhizProjectList& GetProjectList(void) const = 0;

	/**
		@return Returns the file list corresponding to all the open
			projects.
		@see GetProjectList
	**/
	virtual WWhizFileList& GetFileList(void) const = 0;

	/**
		@return Returns the open workspace location.  Note that this location
			is set through the function SetWorkspaceLocation().
		@see SetWorkspaceLocation
	**/
	virtual const CString& GetWorkspaceLocation(void) const = 0;

	/**
		This is a cheap way to obtain the workspace location from DevStudio,
		but it is the only way which consistently worked.  DevStudio provides
		no function to return the location of the workspace.  This function
		does it by obtaining the current working directory when the workspace
		opens.  This is best done by calling WWhizInterface's
		SetWorkspaceLocation() through the DevStudio automation function:
		
		HRESULT CCommands::XApplicationEvents::WorkspaceOpen();

		If the WWhizInterface facilities are being used without DevStudio's
		assistance, then set the current working directory to the directory
		containing the workspace and call SetWorkspaceLocation().

		@code
		_chdir("c:/Projects/MyProject");
		g_wwhizInterface->SetWorkspaceLocation();
		g_wwhizInterface->AddProject("c:/Projects/MyProject/MyProject.dsw");
		@endcode

		Note: A call to SetWorkspaceLocation() is required, because Workspace
		Whiz! files, such as ExtraFiles.WW and Tags.WW, are stored in the
		directory returned via GetWorkspaceLocation().
	**/
	virtual void SetWorkspaceLocation(void) = 0;

	/**
		@return Returns the full path to the ExtraFiles.WW file.
	**/
	virtual const CString& GetExtraFilename(void) = 0;

	/**
		@param filename A reference to a CString where the currently active
			file's full path will be stored.  If DevStudio is not running,
			filename will be an empty string.
		@return Returns true if a filename was able to be retrieved.  False,
			otherwise.
	**/
	virtual bool GetCurrentFilename(CString& filename) const = 0;

	/**
		@return When running DevStudio, returns the WWhizProject interface to
			the currently active project in the workspace.
	**/
	virtual WWhizProject* GetCurrentProject() const = 0;

	/**
		Resolves the filename when it contains environment variables and relative paths.
		Any filename can contain environment variables.  This is especially true of
		DevStudio.

		Filenames containing environment variables are of the form:

		$(MYPROJECTS)\CoolProject\Cool.dsw

		@param rootDir The root directory to be attached to the beginning of
			[filename] if [filename] is a relative path.  If the root
			directory is empty, no string is prepended.
		@param filename The reference to the filename to be resolved.  The
			resolved filename is stored back into this variable.
	**/
	virtual void ResolveFilename(const CString& rootDir, CString& filename) = 0;

	/**
		It is wise to refresh the file list before using any file or tag
		commands.  This is especially true when running in DevStudio.  Since
		DevStudio provides no COM method of retrieving the list of files in
		a project, WWhizInterface is only able to retrieve its file list by
		parsing .dsp files.  This has at least one primary disadvantage.  If
		a change is made to the project in DevStudio, the project MUST be
		saved before WWhizInterface can process the change.

		RefreshFileList() does a scan of .dsp files to determine if
		updates are necessary.  This scan is very quick, so it is advised the
		application calls RefreshFileList() before each set of file or tag
		commands.

		When in DevStudio, RefreshFileList() automatically adds any projects
		in the open workspace.

		If the Workspace Whiz! registration interface is available, ExtraFiles
		are added, also.

		
	**/
	virtual bool RefreshFileList(void) = 0;

	/**
		Adds a project to the list of WWhizInterface projects.  Projects (.dsp)
		or workspaces (.dsw) are the only file types that can be added.

		@param projectName The path to the project or workspace file to be added.
	**/
	virtual void AddProject(CString projectName) = 0;

	/**
		Performs a full cleanup of the WWhizInterface internal structures.
	**/
	virtual void RemoveAllFiles(void) = 0;

	/**
		If the Workspace Whiz! registration interface exists, a comprehensive
		header flip is performed.  Since the registration interface (WWhizReg)
		is not redistributable, this function is only valid if a registered
		Workspace Whiz! is present.

		@return Returns 0 if the flip was performed successfully, -1 otherwise.
	**/
	virtual int HeaderFlip(CString fullName) = 0;

	///////////////////////////////////////////////////////////////////////////
	// Tag support
	///////////////////////////////////////////////////////////////////////////
	/**
		@return After performing a tag match through the MatchTag() function,
			GetTagMatchHead() returns the first found WWhizTag.
	**/
	virtual const WWhizTag* GetTagMatchHead(void) const = 0;

	/**
		@return After performing a tag match through the MatchTag() function,
			GetTagMatchTail() returns the last found WWhizTag.
	**/
	virtual const WWhizTag* GetTagMatchTail(void) const = 0;

	/**
		@return Returns the total number of matched tags found through the
			MatchTag() function.
	**/
	virtual int GetTagMatchCount(void) const = 0;

	/**
		@return If the WWhizReg registration interface exists, returns the
			last tag moved to through GotoTag().
	**/
	virtual const WWhizTag* GetLastMatchedTag(void) const = 0;

	/**
		@return Retrieves the list of tags corresponding to all of the files
			in GetFileList().
	**/
	virtual const WWhizTagList& GetTagList(void) const = 0;

	/**
		Performs a full cleanup of the WWhizInterface internal tag structures.
	**/
	virtual void RemoveAllTags(void) = 0;

	/**
		Matches [name] against a tag list.  The list of matched tags can be
		retrieved through GetTagMatchHead(), GetTagMatchTail(), and
		GetTagMatchCount().  Additionally, WWhizTag::GetMatchNext() and 
		WWhizTag::GetMatchPrev() may be used for traversal.

		@param tags The tag list to match against.
		@param name [name] is of the format described in the Find Tag Workspace
			Whiz! documentation.
	**/
	virtual void MatchTag(const WWhizTagList& tags, LPCTSTR name) const = 0;

	/**
		If the WWhizReg registration interface exists and DevStudio is loaded,
		the appropriate source file is opened and the caret is positioned.

		@param tag The tag to go to.
	**/
	virtual bool GotoTag(const WWhizTag* tag) const = 0;

	/**
		Before calling RefreshTagList(), a tag callback may be set through this
		function.

		@param callback The callback function.
		@param userData User-specified data.
	**/
	virtual void SetTagCallback(TagRefreshCallback callback, void* userData) = 0;

	/**
		Refreshes the tag list.  If WWhizConfig::GetAutoRefreshTags() is not
		set and [forceRefresh] is not set, then the tags aren't refreshed.

		@param forceRefresh Forces a tag refresh.
	**/
	virtual void RefreshTagList(bool forceRefresh = false) = 0;

	/**
		Loads a list of saved tags from the disk.
	**/
	virtual void LoadTags() = 0;

	/**
		Saves the list of tags to the disk.  The tags are saved to the file
		Tags.WW in the directory specified by GetWorkspaceLocation().
	**/
	virtual void SaveTags() = 0;

	/**
		@param The tag type to query.
		@return Returns whether the specified tag type is considered for the
			MatchTag() search.
	**/
	virtual bool GetTagUseType(WWhizTag::Type type) = 0;

	/**
		Sets the tag types considered for the MatchTag() routine.  By default,
		all tag types are on.

		@param type The tag type to turn on/off.
		@param use Set to true if the tag type should be considered for the
			search, false otherwise.
	**/
	virtual void SetTagUseType(WWhizTag::Type type, bool use) = 0;

	// Global files
	/**
		@return Retrieves the global file list, which is the list of files
			queried from the global include directories.  (In DevStudio,
			they are found under Tools->Options->Directories->Include Files.)
	**/
	virtual WWhizFileList& GetGlobalFileList(void) const = 0;

	/**
		Refreshes the global file list.
	**/
	virtual bool RefreshGlobalFileList(void) = 0;
	
	// Misc
	/**
		@return Retrieves the WWhizConfig interface.
	**/
	virtual WWhizConfig& GetConfig() = 0;

	// More stuff appended to the end.
	/**
		@return Retrieves the last time RefreshFileList() found new files.
	**/
	virtual CTime GetLastFileRefreshTime() const = 0;

	/**
		@return Returns the last time RefreshTagList() found new tags.
	**/
	virtual CTime GetLastTagRefreshTime() const = 0;

	/**
		Sets a pointer to the Workspace Whiz! registration module.

		@param wwhizReg The pointer to the WWhizReg.mod.
	**/
	virtual void SetWWhizReg(WWhizReg* wwhizReg) = 0;

	/**
		@return Returns the file list corresponding to all the open
			active projects.
		@see GetProjectList
	**/
	virtual WWhizFileList& GetActiveFileList(void) const = 0;
};


/**
	WWhizInterface configuration information.
**/
class WWhizConfig
{
public:
	///////////////////////////////////////////////////////////////////////////
	// Files extension list.
	///////////////////////////////////////////////////////////////////////////
	/**
		\internal Resets the file extension list to the defaults:

		cpp, c, cxx, cc, h, hpp, hh, inl

		Currently, the list of file extensions is only used by the registration
		module's header flip.
	**/
	virtual void FilesExtReset() = 0;

	/**
		\internal Remove all extensions in the extension list.
	**/
	virtual void FilesExtRemoveAll() = 0;

	/**
		\internal Adds a new file extension.
	**/
	virtual void FilesExtAdd(CString ext) = 0;

	/**
		\internal Removes a file extension.
	**/
	virtual void FilesExtRemove(int index) = 0;

	/**
		\internal Gets a file extension from the list.
	**/
	virtual const CString& FilesExtGet(int index) = 0;

	/**
		\internal Retrieves the number of registered file extensions.
	**/
	virtual int FilesExtGetCount() = 0;

	///////////////////////////////////////////////////////////////////////////
	// Tags extension list.
	///////////////////////////////////////////////////////////////////////////
	/**
		Resets the tag extension list to the defaults:

		cpp, c, cxx, cc, h, hpp, hh, inl

		The list of tag extensions is used when considering which files should
		be processed by CTags.
	**/
	virtual void TagsExtReset() = 0;

	/**
		Remove all extensions in the extension list.
	**/
	virtual void TagsExtRemoveAll() = 0;

	/**
		Adds a new tag file extension.
	**/
	virtual void TagsExtAdd(CString ext) = 0;

	/**
		Removes a tag file extension.
	**/
	virtual void TagsExtRemove(int index) = 0;

	/**
		@return Retrieves the number of registered tag file extensions.
	**/
	virtual int TagsExtGetCount() = 0;

	/**
		@param index The tag extension index to retrieve.
		@return Retrieves a tag extension from the list.
	**/
	virtual const CString& TagsExtGet(int index) = 0;

	// Misc.
	/**
		The tags are automatically saved every x tag refreshes.

		@return Retrieves the number of tag refreshes that must occur before
			the tags are saved to disk.
	**/
	virtual int GetTagAutoSaveAmount() = 0;

	/**
		The tags are automatically saved every x tag refreshes.

		@param amount The number of tag refreshes that must occur before
			the tags are saved to disk.
	**/
	virtual void SetTagAutoSaveAmount(int amount) = 0;

	/**
		@return Retrieves whether tags are automatically force refreshed every
			time WWhizInterface::RefreshTagList() is called.
	**/
	virtual bool GetAutoRefreshTags() = 0;

	/**
		@param autoRefresh Sets whether tags are automatically force refreshed every
			time WWhizInterface::RefreshTagList() is called.
	**/
	virtual void SetAutoRefreshTags(bool autoRefresh) = 0;
	virtual bool GetDoTagExactMatch() = 0;
	virtual void SetDoTagExactMatch(bool exactMatch) = 0;
	virtual bool GetDoTagExactMatchExactLen() = 0;
	virtual void SetDoTagExactMatchExactLen(bool exactLen) = 0;
};


/**
	WWhizProjectList represents the list of projects contained within
	WWhizInterface.
**/
class WWhizProjectList
{
public:
	/**
		@return Retrieves the number of projects in the list.
	**/
	virtual int GetProjectCount() const = 0;

	/**
		@param index The index of the project to retrieve.
		@return Returns the WWhizProject at [index].
	**/
	virtual WWhizProject* GetProjectByIndex(int index) const = 0;

	/**
		Finds a project by full path name.

		@param projectName The full path name to the project.
		@return Returns the WWhizProject matching [projectName].
	**/
	virtual WWhizProject* Find(CString projectName) const = 0;
};


/**
	Represents a single project.
**/
class WWhizProject
{
public:
	/**
		@return Retrieves the full path name to the project.
	**/
	virtual const CString& GetName(void) const = 0;

	/**
		@return Returns whether the project is active.
	**/
	virtual bool IsActive(void) const = 0;

	/**
		@return Retrieves the time stamp of the project file when it was read
			in.
	**/
	virtual const CTime& GetTimeStamp(void) const = 0;

	/**
		@return Retrieves the project's file list.
	**/
	virtual WWhizFileList& GetFileList(void) const = 0;

	/**
		@return Retrieves the project's tag list.
	**/
	virtual WWhizTagList& GetTagList(void) const = 0;

	/**
		@return Returns true if the project is part of the active workspace,
			false otherwise.
	**/
	virtual bool IsWorkspaceProject(void) const = 0;

	/**
		Sets whether the project is active or not.  Be sure to call
		WWhizInterface::RefreshFileList() after making this call.

		@param active The new active state of the project.
	**/
	virtual void SetActive(bool active = true) = 0;
};


/**
	Represents a sorted file list.
**/
class WWhizFileList
{
public:
	/**
		@return Retrieves the count of files in the file list.
	**/
	virtual int GetCount(void) const = 0;

	/**
		@param index The index of the WWhizFile to retrieve.
		@return Retrieves the file at [index].
	**/
	virtual WWhizFile* Get(int index) const = 0;

	/**
		Searches for a file matching [fullName].

		@param fullName The full path name of the file to find, case sensitive.
		@return Returns the WWhizFile of the found file.  If the file was not
			found, returns NULL.
	**/
	virtual WWhizFile* Find(CString fullName) const = 0;

	/**
		Based on an existing WWhizFile, FindExact() finds the index
		corresponding to that file.

		@param An existing WWhizFile, obtained via WWhizFileList::Get() or
			WWhizFileList::Create().
		@return Returns the found index or -1 if not found.
	**/
	virtual int FindExact(WWhizFile& file) const = 0;

	/**
		Based on an existing WWhizFile, FindExact() finds the next index
		corresponding to an approximate file match.

		@param An existing WWhizFile, obtained via WWhizFileList::Get() or
			WWhizFileList::Create().
		@return Returns the found index or -1 if not found.
	**/
	virtual int FindNext(int startPos, WWhizFile& file) const = 0;

	/**
		Based on an existing WWhizFile, FindPrevious() finds the previous 
		index corresponding to an approximate file match.

		@param An existing WWhizFile, obtained via WWhizFileList::Get() or
			WWhizFileList::Create().
		@return Returns the found index or -1 if not found.
	**/
	virtual int FindPrevious(int startPos, WWhizFile& file) const = 0;

	/**
		Based on a filename, Create() returns a new WWhizFile object that
		has a reference count of 1.  The application is responsible for
		calling Release() on the file when done.

		@param filename The filename to create a WWhizFile object from.
		@return A WWhizFile describing [filename].
	**/
	virtual WWhizFile& Create(const CString& filename) = 0;
};


/**
	Represents a file.
**/
class WWhizFile : public WWhizBase
{
public:
	/**
		@return Returns the lowercase version of the full path name.
	**/
	virtual const CString& GetFullName() const = 0;

	/**
		@return Returns the case-sensitive version of the full path name, as it
			appears on disk.
	**/
	virtual CString GetCaseFullName() const = 0;

	/**
		To facilitate faster file lookups, every file has a "short" title
		associated with it.  The short name is all lowercase and only
		contains alphanumeric characters.  Underscores are not included.
		Do not use GetShortName() for the display of the file title.  Instead,
		use GetTitle().

		@return Returns the alphanumeric "short" title for the file.
	**/
	virtual const CString& GetShortName(void) const = 0;

	/**
		@return Returns the case-sensitive file title.
	**/
	virtual const CString& GetTitle(void) const = 0;

	/**
		@return Returns the lowercase file extension.
	**/
	virtual const CString& GetExt(void) const = 0;

	/**
		@return Returns the case-sensitive path name.
	**/
	virtual const CString& GetPath(void) const = 0;

	/**
		@return Returns the file stamp of the file the last time
			WWhizInterface::RefreshFileList() was called.
	**/
	virtual const CTime& GetTimeStamp(void) const = 0;

	/**
		@return Returns the tag list associated with this file.
	**/
	virtual WWhizTagList& GetTagList(void) const = 0;


	/**
		Sets the short name of the file.  Only use this function on file's
		returned via WWhizFileList::Create().

		@param shortName The new short name for the file.
	**/
	virtual void SetShortName(const CString& shortName) = 0;

	/**
		Sets the file title of the file.  Only use this function on file's
		returned via WWhizFileList::Create().

		@param title The new title for the file.
	**/
	virtual void SetTitle(const CString& title) = 0;

	/**
		Sets the extension of the file.  Only use this function on file's
		returned via WWhizFileList::Create().

		@param ext The new extension for the file.
	**/
	virtual void SetExt(const CString& ext) = 0;

	/**
		Sets the path of the file.  Only use this function on file's
		returned via WWhizFileList::Create().

		@param ext The new path for the file.
	**/
	virtual void SetPath(const CString& path) = 0;

	/**
		Sets the time stamp of the file.  Only use this function on file's
		returned via WWhizFileList::Create().

		@param ext The new time stamp for the file.
	**/
	virtual void SetTimeStamp(CTime timeStamp) = 0;
};


/**
	Represents a sorted tag list.
**/
class WWhizTagList
{
public:
	/**
		@return Retrieves the count of tags in the tag list.
	**/
	virtual int GetCount(void) const = 0;

	/**
		@param index The index of the WWhizTag to retrieve.
		@return Retrieves the tag at [index].
	**/
	virtual WWhizTag* Get(int index) const = 0;
};