tagmanager/include/tm_work_object.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_WORK_OBJECT_H
  11 #define TM_WORK_OBJECT_H
  12
  13 #include <stdio.h>
  14 #include <time.h>
  15 #include <glib.h>
  16
  17 #ifdef __cplusplus
  18 extern "C"
  19 {
  20 #endif
  21
  22 // DEBUG. FIXME REMOVE
  23 //#define TM_DEBUG
  24
  25 /*! Evaluates to X is X is defined, else evaluates to Y */
  26 #define NVL(X,Y) (X)?(X):(Y)
  27
  28 /*! Macro to cast a pointer to (TMWorkObject *) */
  29 #define TM_WORK_OBJECT(work_object) ((TMWorkObject *) work_object)
  30
  31 /*!
  32  A TMWorkObject structure is the base class for TMSourceFile and TMProject.
  33  This struct contains data common to all work objects, namely, a file name,
  34  time when the file was analyzed (for caching) and an array of tags which
  35  should be populated when the object is analyzed.
  36 */
  37 typedef struct _TMWorkObject
  38 {
  39         guint type; /*!< The type of object. Can be a source file or a project */
  40         char *file_name; /*!< Full file name (inc. path) of the work object */
  41         char *short_name; /*!< Just the name of the file (without the path) */
  42         struct _TMWorkObject *parent;
  43         time_t analyze_time; /*!< Time when the object was last analyzed */
  44         GPtrArray *tags_array; /*!< Tags obtained by parsing the object */
  45 } TMWorkObject;
  46
  47 /*! Prototype of the update function required to be written by all classes
  48  derived from TMWorkObject. The function should take a pointer to the
  49  object and a flag indicating whether the cache should be ignored, and
  50  update the object's tag array accordingly.
  51  \sa tm_work_object_update(), tm_workspace_update(), tm_project_update(),
  52  tm_source_file_update().
  53 */
  54 typedef gboolean (*TMUpdateFunc) (TMWorkObject *work_object, gboolean force
  55   , gboolean recurse, gboolean update_parent);
  56
  57 /*! Prototype of the find function required to be written by all classed
  58  derived from TMWorkObject. The function should take a pointer to the work
  59  object and a file name and return a pointer to the work object corresponding
  60  to the file name if the file is part of the object, and NULL otherwise.
  61  \sa tm_work_object_find()
  62 */
  63 typedef TMWorkObject *(*TMFindFunc) (TMWorkObject *work_object, const char *file_name
  64   , gboolean name_only);
  65
  66 /*!
  67  Contains pointers to functions necessary to handle virtual function calls
  68  correctly. To create a new object derived from TMWorkObject, you
  69  need to write the three functions specified as the members of this class and
  70  register your class before first use using tm_work_object_register()
  71 */
  72 typedef struct _TMWorkObjectClass
  73 {
  74         GFreeFunc free_func; /*!< Function to free the derived object */
  75         TMUpdateFunc update_func; /*!< Function to update the derived object */
  76         TMFindFunc find_func; /*!< Function to locate contained work objects */
  77 } TMWorkObjectClass;
  78
  79 #define TM_OBJECT_TYPE(work_object) ((TMWorkObject *) work_object)->type /*!< Type of the work object */
  80 #define TM_OBJECT_FILE(work_object) ((TMWorkObject *) work_object)->file_name /*!< File name of the work object */
  81 #define TM_OBJECT_TAGS(work_object) ((TMWorkObject *) work_object)->tags_array /*!< Tag array of the work object */
  82
  83 /*!
  84  Given a file name, returns a newly allocated string containing the realpath()
  85  of the file. However, unlike realpath, a reasonable guess is returned even if
  86  the file does not exist, which may often be the case
  87  \param file_name The original file_name
  88  \return A newly allocated string containing the real path to the file
  89 */
  90 gchar *tm_get_real_path(const gchar *file_name);
  91
  92 /*!
  93  Initializes the work object structure. This function should be called by the
  94  initialization routine of the derived classes to ensure that the base members
  95  are initialized properly. The library user should not have to call this under
  96  any circumstance.
  97  \param work_object The work object to be initialized.
  98  \param type The type of the work object obtained by registering the derived class.
  99  \param file_name The name of the file corresponding to the work object.
 100  \param create Whether to create the file if it doesn't exist.
 101  \return TRUE on success, FALSE on failure.
 102  \sa tm_work_object_register()
 103 */
 104 gboolean tm_work_object_init(TMWorkObject *work_object, guint type, const char *file_name
 105           , gboolean create);
 106
 107 /*!
 108  Initializes a new TMWorkObject structure and returns a pointer to it. You souldn't
 109  have to call this function.
 110  \return NULL on failure
 111  \sa tm_source_file_new() , tm_project_new()
 112 */
 113 TMWorkObject *tm_work_object_new(guint type, const char *file_name, gboolean create);
 114
 115 /*!
 116  Utility function - Given a file name, returns the timestamp of modification.
 117  \param file_name Full path to the file.
 118  \return Timestamp of the file's modification time. 0 on failure.
 119 */
 120 time_t tm_get_file_timestamp(const char *file_name);
 121
 122 /*!
 123  Checks if the work object has been modified since the last update by comparing
 124  the timestamp stored in the work object structure with the modification time
 125  of the physical file.
 126  \param work_object Pointer to the work object.
 127  \return TRUE if the file has changed since last update, FALSE otherwise.
 128 */
 129 gboolean tm_work_object_is_changed(TMWorkObject *work_object);
 130
 131 /*!
 132  Destroys a work object's data without freeing the structure itself. It should
 133  be called by the deallocator function of classes derived from TMWorkObject. The
 134  user shouldn't have to call this function.
 135 */
 136 void tm_work_object_destroy(TMWorkObject *work_object);
 137
 138 /*!
 139  Deallocates a work object and it's component structures. The user can call this
 140  function directly since it will automatically call the correct deallocator function
 141  of the derived class if required.
 142  \param work_object Pointer to a work object or an object derived from it.
 143 */
 144 void tm_work_object_free(gpointer work_object);
 145
 146 /*!
 147  This function should be called exactly once by all classes derived from TMWorkObject,
 148  since it supplies a unique ID on each call and stores the functions to call for
 149  updation and deallocation of objects of the type allocated. The user should not
 150  have to use this function unless he/she wants to create a new class derived from
 151  TMWorkObject.
 152  \param free_func The function to call to free the derived object.
 153  \param update_func The function to call to update the derived object.
 154  \return A unique ID for the derived class.
 155  \sa TMSourceFile , TMProject
 156 */
 157 guint tm_work_object_register(GFreeFunc free_func, TMUpdateFunc update_func, TMFindFunc find_func);
 158
 159 /*!
 160  Writes the tags for the work object to the file specified.
 161  \param work_object The work object whose tags need to be written.
 162  \param file The file to which the tags are to be written.
 163  \param attrs The attributes to write (Can be a bitmask).
 164 */
 165 void tm_work_object_write_tags(TMWorkObject *work_object, FILE *file, guint attrs);
 166
 167 /*!
 168  Updates the tags array if necessary. Automatically calls the update function
 169  of the type to which the object belongs.
 170  \param work_object Pointer to a work object or an object derived from it.
 171  \param force Whether the cache is to be ignored.
 172  \param recurse Whether to recurse into child work objects (for workspace and projects).
 173  \param update_parent If set to TRUE, calls the update function of the parent if required.
 174  If you are calling this function, you should set this to TRUE.
 175  \return TRUE on success, FALSE on failure.
 176  \sa tm_source_file_update() , tm_project_update()
 177 */
 178 gboolean tm_work_object_update(TMWorkObject *work_object, gboolean force
 179   , gboolean recurse, gboolean update_parent);
 180
 181 /*!
 182  Finds the work object corresponding to the file name passed and returns a pointer
 183  to it. If not found, returns NULL. This is a virtual function which automatically
 184  calls the registered find function of teh derived object.
 185  \sa TMFindFunc
 186 */
 187 TMWorkObject *tm_work_object_find(TMWorkObject *work_object, const char *file_name
 188   , gboolean name_only);
 189
 190 /*! Dumps the contents of a work object - useful for debugging */
 191 void tm_work_object_dump(const TMWorkObject *w);
 192
 193 #ifdef __cplusplus
 194 }
 195 #endif
 196
 197 #endif /* TM_WORK_OBJECT_H */