tagmanager/include/tm_file_entry.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_FILE_ENTRY_H
  11 #define TM_FILE_ENTRY_H
  12
  13 #include <glib.h>
  14
  15 /*! \file
  16 The TMFileEntry structure and associated functions can be used
  17 for file and directory traversal. The following example demonstrates
  18 the use of TMFileEntry.
  19 \include tm_file_tree_dump.c
  20 */
  21
  22 #ifdef __cplusplus
  23 extern "C"
  24 {
  25 #endif
  26
  27 // DEBUG. FIXME REMOVE
  28 //#define TM_DEBUG
  29
  30
  31 /*! Enum defining file types */
  32 typedef enum
  33 {
  34         tm_file_unknown_t, /*!< Unknown file type/file does not exist */
  35         tm_file_regular_t, /*!< Is a regular file */
  36         tm_file_dir_t, /*!< Is a directory */
  37         tm_file_link_t /*!< Is a symbolic link */
  38 } TMFileType;
  39
  40 /*!
  41  This example demonstrates the use of TMFileEntry and associated functions
  42  for managing file hierarchies in a project.
  43
  44  \example tm_file_tree_dump.c
  45 */
  46
  47 /*! This structure stores the file tree */
  48 typedef struct _TMFileEntry
  49 {
  50         TMFileType type; /*!< File type */
  51         char *path; /*!< Full path to the file (incl. dir and name) */
  52         char *name; /*!< Just the file name (path minus the directory) */
  53         char *version; /*!< CVS version in case there is a CVS entry for this file */
  54         struct _TMFileEntry *parent; /*!< The parent directory file entry */
  55         GSList *children; /*!< List of children (for directory) */
  56 } TMFileEntry;
  57
  58 /*! Prototype for the function that gets called for each entry when
  59  tm_file_entry_foreach() is called.
  60 */
  61 typedef void (*TMFileEntryFunc) (TMFileEntry *entry, gpointer user_data
  62   , guint level);
  63
  64 /*! Convinience casting macro */
  65 #define TM_FILE_ENTRY(E) ((TMFileEntry *) (E))
  66
  67 /*! Function that compares two file entries on name and returns the
  68  difference
  69 */
  70 gint tm_file_entry_compare(TMFileEntry *e1, TMFileEntry *e2);
  71
  72 /*! Function to create a new file entry structure.
  73 \param path Path to the file for which the entry is to be created.
  74 \param parent Should be NULL for the first call. Since the function calls
  75  itself recursively, this parameter is required to build the hierarchy.
  76 \param recurse Whether the entry is to be recursively scanned (for
  77  directories only)
  78 \param file_match List of file name patterns to match. If set to NULL,
  79  all files match. You can use wildcards like '*.c'. See the example program
  80  for usage.
  81 \param file_unmatch Opposite of file_match. All files matching any of the patterns
  82  supplied are ignored. If set to NULL, no file is ignored.
  83 \param dir_match List of directory name patterns to match. If set to NULL,
  84  all directories match. You can use wildcards like '\.*'.
  85 \param dir_unmatch Opposite of dir_match. All directories matching any of the
  86  patterns supplied are ignored. If set to NULL, no directory is ignored.
  87 \param ignore_hidden_files If set to TRUE, hidden files (starting with '.')
  88  are ignored.
  89 \param ignore_hidden_dirs If set to TRUE, hidden directories (starting with '.')
  90  are ignored.
  91 \return Populated TMFileEntry structure on success, NULL on failure.
  92 */
  93 TMFileEntry *tm_file_entry_new(const char *path, TMFileEntry *parent
  94   , gboolean recurse, GList *file_match, GList *file_unmatch
  95   , GList *dir_match, GList *dir_unmatch, gboolean ignore_hidden_files
  96   , gboolean ignore_hidden_dirs);
  97
  98 /*! Frees a TMFileEntry structure. Freeing is recursive, so all child
  99  entries are freed as well.
 100 \param entry The TMFileEntry structure to be freed.
 101 */
 102 void tm_file_entry_free(gpointer entry);
 103
 104 /*! This will call the function func() for each file entry.
 105 \param entry The root file entry.
 106 \param func The function to be called.
 107 \param user_data Extra information to be passed to the function.
 108 \param level The recursion level. You should set this to 0 initially.
 109 \param reverse If set to TRUE, traversal is in reverse hierarchical order
 110 */
 111 void tm_file_entry_foreach(TMFileEntry *entry, TMFileEntryFunc func
 112   , gpointer user_data, guint level, gboolean reverse);
 113
 114 /*! This is a sample function to show the use of tm_file_entry_foreach().
 115 */
 116 void tm_file_entry_print(TMFileEntry *entry, gpointer user_data, guint level);
 117
 118 /* Creates a list of path names from a TMFileEntry structure.
 119 \param entry The TMFileEntry structure.
 120 \files Current file list. Should be NULL.
 121 */
 122 GList *tm_file_entry_list(TMFileEntry *entry, GList *files);
 123
 124 #ifdef __cplusplus
 125 }
 126 #endif
 127
 128 #endif /* TM_FILE_ENTRY_H */