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