tagmanager/src/tm_project.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_PROJECT_H
  11 #define TM_PROJECT_H
  12
  13 #include <glib.h>
  14 #include "tm_work_object.h"
  15
  16
  17 /*! \file
  18  The TMProject structure and associated functions can be used to group together
  19  related source files in a "project". The update, open and save functions take
  20  care of automatically updating the project database whenever one or more
  21  files are changed. The following example demonstrates the use of TMProject.
  22
  23  \include tm_project_test.c
  24 */
  25
  26 #ifdef __cplusplus
  27 extern "C"
  28 {
  29 #endif
  30
  31 /*! Casts a pointer to a pointer to a TMProject structure */
  32 #define TM_PROJECT(work_object) ((TMProject *) (work_object))
  33
  34 /*! Checks whether the object is a TMProject */
  35 #define IS_TM_PROJECT(work_object) ((work_object)->type == project_class_id)
  36
  37 /*!
  38  This example demonstrates the use of TMProject and associated functions
  39  for managing tags for a group of related source files.
  40
  41  \example tm_project_test.c
  42 */
  43
  44 /*!
  45  The TMProject structure is derived from TMWorkObject and contains all it's
  46  attributes, plus a project name and a list of source files constituting the project.
  47 */
  48 typedef struct _TMProject
  49 {
  50         TMWorkObject work_object; /*!< The parent work object */
  51         char *dir; /*!< Top project directory */
  52         const char **sources; /*!< Extensions for source files (wildcards, NULL terminated) */
  53         const char **ignore; /*!< File patters to ignore */
  54         GPtrArray *file_list; /*!< Array of TMSourceFile present in the project */
  55 } TMProject;
  56
  57 /*! Initializes a TMProject structure from specified parameters
  58  \param project The TMProject structure to initialize.
  59  \param dir The top level directory of the project.
  60  \param sources The source files you are interested in (as wildcards).
  61  \param ignore The files you are not interested in (as wildcards).
  62  \param force Ignore cache (do full-scan of project directory)
  63  */
  64 gboolean tm_project_init(TMProject *project, const char *dir
  65   , const char **sources, const char **ignore, gboolean force);
  66
  67 /*! Initializes a TMProject structure with the given parameters and
  68  returns a pointer to it. The function looks for a file called 'tm.tags'
  69  inside the top level directory to load the project. If such a file is not
  70  found, it assumes autoscan mode and imports all source files
  71  by recursively scanning the directory for Makefile.am and importing them.
  72  If top Makefile.am is missing as well, it simply imports all source files.
  73  \param dir The top level directory for the project.
  74  \param sources The list of source extensions. This should be a NULL terminated
  75  list of wildcards for the source types that you want to get displayed
  76  in the source tree. If the default list is acceptable, use NULL.
  77  \param ignore A NULL terminated list of wildcards for files to ignore
  78  \param force Ignore cache if present (treat as new project)
  79  \sa tm_project_init() , tm_project_autoscan()
  80 */
  81 TMWorkObject *tm_project_new(const char *dir, const char **sources
  82   , const char **ignore, gboolean force);
  83
  84 /*! Destroys the contents of the project. Note that the tags are owned by the
  85  source files of the project, so they are also destroyed as each source file
  86  is deallocated using tm_source_file_free(). If the tags are to be used after
  87  the project has been destroyed, they should be deep-copied and any arrys
  88  containing pointers to them should be rebuilt. Destroying a project will
  89  automatically update and save teh project if required. You should not have
  90  to use this function since this is automatically called by tm_project_free().
  91  \param project The project to be destriyed.
  92 */
  93 void tm_project_destroy(TMProject *project);
  94
  95 /*! Destroys the project contents by calling tm_project_destroy() and frees the
  96  memory allocated to the project structure.
  97  \sa tm_project_destroy()
  98 */
  99 void tm_project_free(gpointer project);
 100
 101 /*! Opens a project by reading contents from the project database. The project
 102  should have been initialized prior to this using tm_project_new(). You should
 103  not have to use this since tm_project_new() will open the project if it already
 104  exists.
 105  \param project The project to open.
 106  \param force Whether the cache should be ignored.
 107  \return TRUE on success, FALSE on failure
 108 */
 109 gboolean tm_project_open(TMProject *project, gboolean force);
 110
 111 /*! Saves the project in the project database file.
 112  \param project The project to save.
 113  \return TRUE on success, FALSE on failure.
 114 */
 115 gboolean tm_project_save(TMProject *project);
 116
 117 /*! Adds a file to the project by creating a TMSourceFile from the file name
 118  and pushing it at the end of the project's file list.
 119  \param project The project to add the file to.
 120  \param file_name Full path of the file to be added to the project.
 121  \param update Whether to update tags image after addition.
 122  \return TRUE on success, FALSE on failure.
 123 */
 124 gboolean tm_project_add_file(TMProject *project, const char *file_name
 125   , gboolean update);
 126
 127 /*! Finds a file in a project. If the file exists, returns a pointer to it,
 128  else returns NULL. This is the overloaded function TMFindFunc for TMProject.
 129  You should not have to call this function directly since this is automatically
 130  called by tm_work_object_find().
 131  \param project The project in which the file is to be searched.
 132  \param The name of the file to be searched.
 133  \param name_only Whether the comparison is to be only on name (not full path)
 134  \return Pointer the file (TMSourceFile) in the project. NULL if the file was not found.
 135 */
 136 TMWorkObject *tm_project_find_file(TMWorkObject *work_object, const char *file_name
 137   , gboolean name_only);
 138
 139 /*! Destroys a member object and removes it from the project list.
 140  \param project The project from the file is to be removed.
 141  \param w The member work object (source file) to be removed
 142  \return TRUE on success, FALSE on failure
 143 */
 144 gboolean tm_project_remove_object(TMProject *project, TMWorkObject *w);
 145
 146 /*! Removes only the project-tags associated with the object. Then resort the project's tags.
 147  \param project The project from which the file's tags are to be removed.
 148  \param w The member work object (source file) to remove the tags.
 149  \return TRUE on success, FALSE on failure
 150 */
 151 gboolean tm_project_remove_tags_from_list(TMProject *project, TMWorkObject *w);
 152
 153 /*! Updates the project database and all the source files contained in the
 154  project. All sorting and deduping is lost and should be redone.
 155  \param work_object The project to update.
 156  \param force If set to TRUE, the cache is ignored.
 157  \param recurse If set to TRUE, checks all child objects, otherwise just recreates the
 158  tag array.
 159  \param update_parent If set to TRUE, sends an update signal to it's parent if required.
 160  If you are calling this function directly, you should always set this to TRUE.
 161  \return TRUE on success, FALSE on failure
 162 */
 163 gboolean tm_project_update(TMWorkObject *work_object, gboolean force
 164   , gboolean recurse, gboolean update_parent);
 165
 166 /*! Syncs a project with the given list of file names, i.e., removes all files
 167 ** which are not in the list and adding the files which are in the list but not
 168 ** in the project.
 169 \param project The project pointer
 170 \param files - A list of file names relative to the top directory.
 171 */
 172 gboolean tm_project_sync(TMProject *project, GList *files);
 173
 174 /*! Recreates the tags array of the project from the tags arrays of the contituent
 175  source files. Note that unlike TMSourceFile , the projects tags are not owned
 176  by the project but by the member source files. So, do not do a tm_tag_free() on
 177  a tag of the project's tag list
 178 */
 179 void tm_project_recreate_tags_array(TMProject *project);
 180
 181 /*! Automatically imports all source files from the given directory
 182  into the project. This is done automatically if tm_project_new() is
 183  supplied with a directory name as parameter. Auto-scan will occur only
 184  if the directory is a valid top-level project directory, i.e, if the
 185  directory contains one of Makefile.am, Makefile.in or Makefile.
 186 */
 187 gboolean tm_project_autoscan(TMProject *project);
 188
 189 /*! Dumps the current project structure - useful for debugging */
 190 void tm_project_dump(const TMProject *p);
 191
 192 /*! Returns TRUE if the passed file is a source file as matched by the project
 193   source extensions (project->extn)
 194 */
 195 gboolean tm_project_is_source_file(TMProject *project, const char *file_name);
 196
 197 /*! Contains the id obtained by registering the TMProject class as a child of
 198  TMWorkObject.
 199  \sa tm_work_object_register()
 200 */
 201 extern guint project_class_id;
 202
 203 #ifdef __cplusplus
 204 }
 205 #endif
 206
 207 #endif /* TM_PROJECT_H */