tagmanager/include/tm_source_file.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_SOURCE_FILE_H
  11 #define TM_SOURCE_FILE_H
  12
  13 #include "tm_work_object.h"
  14
  15 /*! \file
  16  The TMSourceFile structure and associated functions are used to maintain
  17  tags for individual files. See the test file tm_source_file_test.c included
  18  below for an example of how to use this structure and the related functions.
  19
  20  \include tm_tag_print.c
  21
  22 */
  23
  24 #ifndef LIBCTAGS_DEFINED
  25 typedef int langType;
  26 typedef void tagEntryInfo;
  27 #endif
  28
  29
  30 #if !defined(tagEntryInfo)
  31 #endif
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #endif
  37
  38 /*! Casts a pointer to a pointer to a TMSourceFile structure */
  39 #define TM_SOURCE_FILE(work_object) ((TMSourceFile *) work_object)
  40
  41 /*! Checks whether the object is a TMSourceFile */
  42 #define IS_TM_SOURCE_FILE(source_file) (((TMWorkObject *) (source_file))->type \
  43                         == source_file_class_id)
  44
  45 /*!
  46  This example demonstrates the use of the TMSourceFile structure. When run,
  47  it outputs the tags encountered in the source files specified in the command line.
  48
  49  \example tm_tag_print.c
  50 */
  51
  52 /*!
  53  The TMSourceFile structure is derived from TMWorkObject and contains all it's
  54  attributes, plus an integer representing the language of the file.
  55 */
  56 typedef struct _TMSourceFile
  57 {
  58         TMWorkObject work_object; /*!< The base work object */
  59         langType lang; /*!< Programming language used */
  60         gboolean inactive; /*!< Whether this file should be scanned for tags */
  61 } TMSourceFile;
  62
  63 /*! Initializes a TMSourceFile structure from a file name. */
  64 gboolean tm_source_file_init(TMSourceFile *source_file, const char *file_name, gboolean update);
  65
  66 /*! Initializes a TMSourceFile structure and returns a pointer to it. */
  67 TMWorkObject *tm_source_file_new(const char *file_name, gboolean update);
  68
  69 /*! Destroys the contents of the source file. Note that the tags are owned by the
  70  source file and are also destroyed when the source file is destroyed. If pointers
  71  to these tags are used elsewhere, then those tag arrays should be rebuilt.
  72 */
  73 void tm_source_file_destroy(TMSourceFile *source_file);
  74
  75 /*! Frees a TMSourceFile structure, including all contents */
  76 void tm_source_file_free(gpointer source_file);
  77
  78 /*! Updates the source file by reparsing is the modification time is greater
  79  than the timestamp in the structure, or if force is TRUE. The tags array and
  80  the tags themselves are destroyed and re-created, hence any other tag arrays
  81  pointing to these tags should be rebuilt as well. All sorting information is
  82  also lost. The language parameter is automatically set the first time the file
  83  is parsed.
  84  \param source_file The source file to update.
  85  \param force Whether the cache is to be ignored.
  86  \param recurse This parameter is ignored for source files and is only there for consistency.
  87  \param update_parent If set to TRUE, sends an update signal to parent if required. You should
  88  always set this to TRUE if you are calling this function directly.
  89  \return TRUE if the file was parsed, FALSE otherwise.
  90  \sa tm_work_object_update(), tm_project_update(), tm_workspace_update()
  91 */
  92 gboolean tm_source_file_update(TMWorkObject *source_file, gboolean force
  93   , gboolean recurse, gboolean update_parent);
  94
  95 /*! Updates the source file by reparsing the text-buffer passed as parameter.
  96  Ctags will use a parsing based on buffer instead of on files.
  97  You should call this function when you don't want a previous saving of the file
  98  you're editing. It's useful for a "real-time" updating of the tags.
  99  The tags array and the tags themselves are destroyed and re-created, hence any
 100  other tag arrays pointing to these tags should be rebuilt as well. All sorting
 101  information is also lost. The language parameter is automatically set the first
 102  time the file is parsed.
 103  \param source_file The source file to update with a buffer.
 104  \param text_buf A text buffer. The user should take care of allocate and free it after
 105  the use here.
 106  \param text_buf_size The size of text_buf.
 107  \param update_parent If set to TRUE, sends an update signal to parent if required. You should
 108  always set this to TRUE if you are calling this function directly.
 109  \return TRUE if the file was parsed, FALSE otherwise.
 110  \sa tm_work_object_update(), tm_project_update(), tm_workspace_update()
 111 */
 112 gboolean tm_source_file_buffer_update(TMWorkObject *source_file, unsigned char* text_buf
 113         , int text_buf_size, gboolean update_parent);
 114
 115 /*! Parses the source file and regenarates the tags.
 116  \param source_file The source file to parse
 117  \return TRUE on success, FALSE on failure
 118  \sa tm_source_file_update()
 119 */
 120 gboolean tm_source_file_parse(TMSourceFile *source_file);
 121
 122 /*! Parses the text-buffer and regenarates the tags.
 123  \param source_file The source file to parse
 124  \param text_buf The text buffer to parse
 125  \param text_buf_size The size of text_buf.
 126  \return TRUE on success, FALSE on failure
 127  \sa tm_source_file_update()
 128 */
 129 gboolean tm_source_file_buffer_parse(TMSourceFile *source_file, unsigned char* text_buf
 130                 , int text_buf_size);
 131
 132 /*!
 133  This function is registered into the ctags parser when a file is parsed for
 134  the first time. The function is then called by the ctags parser each time
 135  it finds a new tag. You should not have to use this function.
 136  \sa tm_source_file_parse()
 137 */
 138 int tm_source_file_tags(const tagEntryInfo *tag);
 139
 140 /*!
 141  Writes all tags of a source file (including the file tag itself) to the passed
 142  file pointer.
 143  \param source_file The source file to write.
 144  \param fp The file pointer to write to.
 145  \attrs The attributes to write.
 146  \return TRUE on success, FALSE on failure.
 147 */
 148 gboolean tm_source_file_write(TMWorkObject *source_file, FILE *fp, guint attrs);
 149
 150 /*! Contains the id obtained by registering the TMSourceFile class as a child of
 151  TMWorkObject.
 152  \sa tm_work_object_register()
 153 */
 154 extern guint source_file_class_id;
 155
 156 #ifdef __cplusplus
 157 }
 158 #endif
 159
 160 #endif /* TM_SOURCE_FILE_H */