tagmanager/include/tm_workspace.h

   1 /*
   2 *
   3 *   Copyright (c) 2001-2002, Biswapesh Chattopadhyay
   4 *
   5 *   This source code is released for free distribution under the terms of the
   6 *   GNU General Public License.
   7 *
   8 */
   9
  10 #ifndef TM_WORKSPACE_H
  11 #define TM_WORKSPACE_H
  12
  13 #include <glib.h>
  14
  15 // DEBUG. FIXME REMOVE
  16 //#define TM_DEBUG
  17
  18
  19 #include "tm_work_object.h"
  20
  21 /*! \file
  22  The TMWorkspace structure is meant to be used as a singleton to store application
  23  wide tag information. The workspace is intended to contain a list of global tags
  24  and a set of work objects (projects or individual files). You need not use the
  25  workspace, though, to use tag manager, unless you need things like global tags
  26  and a place to store all current open projects and individual files. TMWorkspace
  27  is derived from TMWorkObject.
  28
  29  The following example demonstrates the use of workspace functions to create global tags.
  30  \include tm_global_tags.c
  31 */
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #endif
  37
  38 /*!
  39  This example demonstrates the use of the global tag generation function.
  40
  41  \example tm_global_tags.c
  42 */
  43
  44 /*! The Tag Manager Workspace. This is a singleton work object containing a list
  45  of work objects. These can be either individual files or project containing
  46  multiple files. There is also a global tag list which can be loaded or
  47  created. This contains global tags gleaned from /usr/include, etc. and
  48  should be used for autocompletion, calltips, etc.
  49 */
  50 typedef struct _TMWorkspace
  51 {
  52         TMWorkObject work_object; /*!< The parent work object */
  53         GPtrArray *global_tags; /*!< Global tags loaded at startup */
  54         GPtrArray *work_objects; /*!< An array of TMWorkObject pointers */
  55 } TMWorkspace;
  56
  57 /*! Since TMWorkspace is a singleton, you should not create multiple
  58  workspaces, but get a pointer to the workspace whenever required. The first
  59  time a pointer is requested, or a work object is added to the workspace,
  60  a workspace is created. Subsequent calls to the function will return the
  61  created workspace.
  62 */
  63 const TMWorkspace *tm_get_workspace(void);
  64
  65 /*! Adds a work object (source file or project) to the workspace.
  66  \param work_object The work object to add to the project.
  67  \return TRUE on success, FALSE on failure (e.g. object already exixts).
  68 */
  69 gboolean tm_workspace_add_object(TMWorkObject *work_object);
  70
  71 /*! Given a file name, returns a pointer to the object if the object's file
  72  name is same as the passed file name, otherwise returns NULL. This is an
  73  overloaded version of tm_work_object_find().
  74  \param work_object Pointer to the workspace.
  75  \param file_name The name of the file to search.
  76  \param name_only If you want to match just the name and not the full path.
  77  \return Pointer to the work object matching the file name (NULL if not found).
  78  \sa tm_work_object_find(), tm_project_find_file().
  79 */
  80 TMWorkObject *tm_workspace_find_object(TMWorkObject *work_object, const char *file_name
  81   ,gboolean name_only);
  82
  83 /*! Removes a member object from the workspace if it exists.
  84  \param work_object Pointer to the work object to be removed.
  85  \param free Whether the work object is to be freed as well.
  86  \return TRUE on success, FALSE on failure (e.g. the work object does not exist).
  87 */
  88 gboolean tm_workspace_remove_object(TMWorkObject *work_object, gboolean free);
  89
  90 /*! Loads the global tag list from the specified file. The global tag list should
  91  have been first created using tm_workspace_create_global_tags().
  92  \param tags_file The file containing global tags.
  93  \return TRUE on success, FALSE on failure.
  94  \sa tm_workspace_create_global_tags()
  95 */
  96 gboolean tm_workspace_load_global_tags(const char *tags_file);
  97
  98 /*! Reloads the global tag list from the specified file. The global tag list should
  99  have been first created using tm_workspace_create_global_tags().
 100  \param tags_file The file containing global tags.
 101  \return TRUE on success, FALSE on failure.
 102  \sa tm_workspace_create_global_tags()
 103 */
 104 gboolean tm_workspace_reload_global_tags(const char *tags_file);
 105
 106 /*! Creates a list of global tags. Ideally, this should be created once during
 107  installations so that all users can use the same file. This is because a full
 108  scale global tag list can occupy several megabytes of disk space.
 109  \param pre_process The pre-processing command. This is executed via system(),
 110  so you can pass stuff like 'gcc -E -dD -P `gnome-config --cflags gnome`'.
 111  \param includes Include files to process. Wildcards such as '/usr/include/a*.h'
 112  are allowed.
 113  \param tags_file The file where the tags will be stored.
 114  \return TRUE on success, FALSE on failure.
 115 */
 116 gboolean tm_workspace_create_global_tags(const char *pre_process, const char **includes
 117   , int includes_count, const char *tags_file);
 118
 119 /*! Merges a list of tags files and saves the output in the provided file.
 120  \param output_file Out put file.
 121  \param tag_files GList of files. The files could be gzipped files.
 122  \return TRUE on success, FALSE on failure.
 123 */
 124 gboolean tm_workspace_merge_global_tags (const gchar *output_file,
 125                                                                                  GList *tag_files);
 126
 127 /*! Recreates the tag array of the workspace by collecting the tags of
 128  all member work objects. You shouldn't have to call this directly since
 129  this is called automatically by tm_workspace_update().
 130 */
 131 void tm_workspace_recreate_tags_array(void);
 132
 133 /*! Calls tm_work_object_update() for all workspace member work objects.
 134  Use if you want to globally refresh the workspace.
 135  \param workspace Pointer to the workspace.
 136  \param force Whether the cache should be ignored.
 137  \param recurse If set to TRUE, updates all children before updating the tag image.
 138  \param update_parent This parameter is ignored for the workspace since it is at the
 139  top of the work object hierarchy.
 140  \sa tm_work_object_update(), tm_source_file_update(), tm_project_update()
 141 */
 142 gboolean tm_workspace_update(TMWorkObject *workspace, gboolean force
 143   , gboolean recurse, gboolean update_parent);
 144
 145 /*! Dumps the workspace tree - useful for debugging */
 146 void tm_workspace_dump(void);
 147
 148 /*! Returns all matching tags found in the workspace.
 149  \param name The name of the tag to find.
 150  \param type The tag types to return (TMTagType). Can be a bitmask.
 151  \param attrs The attributes to sort and dedup on (0 terminated integer array).
 152  \param partial Whether partial match is allowed.
 153  \return Array of matching tags. Do not free() it since it is a static member.
 154 */
 155 const GPtrArray *tm_workspace_find(const char *name, int type, TMTagAttrType *attrs
 156  , gboolean partial, gboolean global_search);
 157
 158 /*! Returns all matching members tags found in given struct/union/class name.
 159  \param name Name of the struct/union/class.
 160  \param file_tags A GPtrArray of edited file TMTag pointers (for search speedup, can be NULL).
 161  \return A GPtrArray of TMTag pointers to struct/union/class members */
 162 const GPtrArray *tm_workspace_find_scope_members(const GPtrArray *file_tags,
 163                                                                                                  const char *scope_name,
 164                                                                                                  gboolean find_global,
 165                                                                                                  gboolean no_definitions);
 166
 167
 168 // DEBUG.
 169 const GPtrArray *
 170 tm_workspace_find_namespace_members (const GPtrArray * file_tags, const char *name,
 171                                                                  gboolean search_global);
 172
 173
 174 /*! Returns TMTag to function which "own" given line
 175  \param line Current line in edited file.
 176  \param file_tags A GPtrArray of edited file TMTag pointers.
 177  \return TMTag pointers to owner function. */
 178 const TMTag *tm_get_current_function(GPtrArray *file_tags, const gulong line);
 179
 180 /*! Returns a list of parent classes for the given class name
 181  \param name Name of the class
 182  \return A GPtrArray of TMTag pointers (includes the TMTag for the class) */
 183 const GPtrArray *tm_workspace_get_parents(const gchar *name);
 184
 185 /*! Frees the workspace structure and all child work objects. Use only when
 186  exiting from the main program.
 187 */
 188 void tm_workspace_free(gpointer workspace);
 189
 190 extern guint workspace_class_id;
 191
 192 #ifdef __cplusplus
 193 }
 194 #endif
 195
 196 #endif /* TM_WORKSPACE_H */