git.oblomov.eu Git - ohcount/blob - src/sourcefile.h

   1 // sourcefile.h written by Mitchell Foral. mitchell<att>caladbolg.net.
   2 // See COPYING for license information.
   3
   4 #ifndef OHCOUNT_SOURCEFILE_H
   5 #define OHCOUNT_SOURCEFILE_H
   6
   7 #include "loc.h"
   8 #include "parsed_language.h"
   9
  10 /**
  11  * Creates and returns a new SourceFile from a given filepath.
  12  * The given filepath is copied and may be 'free'd immediately.
  13  * @param filepath The path to a file on disk.
  14  * @return SourceFile
  15  */
  16 SourceFile *ohcount_sourcefile_new(const char *filepath);
  17
  18 /**
  19  * Sets the filepath on the disk of the given SourceFile.
  20  * This is only used if the SourceFile's filepath field is not accurate,
  21  * typically only in language detection.
  22  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
  23  * @param diskpath The real path to the file on disk.
  24  */
  25 void ohcount_sourcefile_set_diskpath(SourceFile *sourcefile,
  26                                      const char *diskpath);
  27
  28 /**
  29  * Sets the contents of the given SourceFile.
  30  * The given contents are copied and may be 'free'd immediately.
  31  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
  32  * @param contents The contents to set for sourcefile.
  33  */
  34 void ohcount_sourcefile_set_contents(SourceFile *sourcefile,
  35                                      const char *contents);
  36
  37 /**
  38  * Returns the file contents of a given SourceFile.
  39  * The returned pointer is used internally and may not be 'free'd.
  40  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
  41  * @return pointer to string file contents.
  42  */
  43 char *ohcount_sourcefile_get_contents(SourceFile *sourcefile);
  44
  45 /**
  46  * Returns the size of the file contents of a given SourceFile.
  47  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
  48  * @return size of the file's contents.
  49  */
  50 int ohcount_sourcefile_get_contents_size(SourceFile *sourcefile);
  51
  52 /**
  53  * Sets the language of a given SourceFile.
  54  * The given language is not copied and may not be 'free'd. Use a language
  55  * defined in src/languages.h.
  56  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
  57  * @param language The language to set the SourceFile to.
  58  */
  59 void ohcount_sourcefile_set_language(SourceFile *sourcefile,
  60                                      const char *language);
  61
  62 /**
  63  * Returns the detected language of a given SourceFile.
  64  * The returned pointer is used internally and may not be 'free'd.
  65  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
  66  * @return string language name.
  67  */
  68 const char *ohcount_sourcefile_get_language(SourceFile *sourcefile);
  69
  70 /**
  71  * Parses the given SourceFile with the default callback that keeps track of the
  72  * number of lines of code, comments, and blank lines.
  73  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
  74  */
  75 void ohcount_sourcefile_parse(SourceFile *sourcefile);
  76
  77 /**
  78  * Returns the ParsedLanguageList parsed out of the given SourceFile.
  79  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
  80  * @return ParsedLanguageList
  81  */
  82 ParsedLanguageList *ohcount_sourcefile_get_parsed_language_list(SourceFile
  83                                                                 *sourcefile);
  84
  85 /**
  86  * Parses the given SourceFile with a specific callback.
  87  * The callback is called for each line parsed, not entity.
  88  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
  89  * @param callback The callback function to call for every line parsed.
  90  * @param userdata Userdata to pass to the callback function.
  91  */
  92 void ohcount_sourcefile_parse_with_callback(SourceFile *sourcefile,
  93                                             void (*callback) (const char *,
  94                                                               const char *, int,
  95                                                               int, void *),
  96                                             void *userdata);
  97
  98 /**
  99  * Parses the given SourceFile with a specific callback.
 100  * The callback is called for each entity parsed, not line.
 101  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
 102  * @param callback The callback function to call for every entity parsed.
 103  * @param userdata Userdata to pass to the callback function.
 104  */
 105 void ohcount_sourcefile_parse_entities_with_callback(SourceFile *sourcefile,
 106                                                      void (*callback)
 107                                                        (const char *,
 108                                                         const char *, int,
 109                                                         int, void *),
 110                                                      void *userdata);
 111
 112 /**
 113  * Returns a LicenseList of detected licenses in the given SourceFile.
 114  * The returned list and its contents are used internally and may not be
 115  * 'free'd.
 116  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
 117  * @return LicenseList
 118  */
 119 LicenseList *ohcount_sourcefile_get_license_list(SourceFile *sourcefile);
 120
 121 /**
 122  * Returns a LocList of total lines of code in each language in the given
 123  * SourceFile.
 124  * The returned list and its contents are used internally and may not be
 125  * 'free'd.
 126  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
 127  * @return LocList
 128  */
 129 LocList *ohcount_sourcefile_get_loc_list(SourceFile *sourcefile);
 130
 131 /**
 132  * Returns a LocDeltaList reflecting the changes from one revision of a
 133  * SourceFile to another for all languages.
 134  * The returned pointer must be 'free'd.
 135  * @param from The reference SourceFile created by ohcount_sourcefile_new().
 136  * @param to The SourceFile to compare the reference SourceFile to (typically a
 137  *   later revision instead of a completely different SourceFile).
 138  * @return LocDeltaList
 139  */
 140 LocDeltaList *ohcount_sourcefile_diff(SourceFile *from, SourceFile *to);
 141
 142 /**
 143  * Returns a LocDelta reflecting the changes from one revision of a SourceFile
 144  * to another for a given language.
 145  * The given language is not copied and may not be 'free'd. Use a language
 146  * defined in src/languages.h.
 147  * The returned pointer must be 'free'd.
 148  * @param from The reference SourceFile created by ohcount_sourcefile_new().
 149  * @param language The language to calculate the LocDelta from.
 150  * @param to The SourceFile to compare the reference SourceFile to (typically a
 151  *   later revision instead of a completely different SourceFile).
 152  * @return LocDelta
 153  */
 154 LocDelta *ohcount_sourcefile_calc_loc_delta(SourceFile *from,
 155                                             const char *language,
 156                                             SourceFile *to);
 157
 158 /**
 159  * Sets the given SourceFile's directory contents to the string array given.
 160  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
 161  * @param filenames String array of filenames. If NULL, the next call to
 162  *   ohcount_sourcefile_get_filenames will access the SourceFile's directory.
 163  */
 164 void ohcount_sourcefile_set_filenames(SourceFile *sourcefile,
 165                                       char **filenames);
 166
 167 /**
 168  * Returns a string array of the given SourceFile's directory contents.
 169  * If the existing 'filenames' field is NULL, the directory is accessed and its
 170  * listing is returned.
 171  * The returned pointer and its contents are used internally and must not be
 172  * 'free'd.
 173  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
 174  * @return pointer to a list of filenames (NULL-pointer terminated).
 175  */
 176 char **ohcount_sourcefile_get_filenames(SourceFile *sourcefile);
 177
 178 /**
 179  * Frees a SourceFile created by ohcount_sourcefile_new().
 180  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
 181  */
 182 void ohcount_sourcefile_free(SourceFile *sourcefile);
 183
 184 /**
 185  * Creates a new SourceFileList that is initially empty.
 186  * Files can be added using ohcount_sourcefile_list_add_file().
 187  * Directories can be added using ohcount_sourcefile_list_add_directory().
 188  * @return SourceFileList
 189  */
 190 SourceFileList *ohcount_sourcefile_list_new();
 191
 192 /**
 193  * Adds a given file to a SourceFileList.
 194  * The given filepath is copied and may be 'free'd immediately.
 195  * @param list a SourceFileList created by ohcount_sourcefile_list_new().
 196  * @param filepath The full path to the file to be added to the list.
 197  */
 198 void ohcount_sourcefile_list_add_file(SourceFileList *list,
 199                                           const char *filepath);
 200
 201 /**
 202  * Adds the contents of a given directory to a SourceFileList.
 203  * The given directory may be 'free'd immediately.
 204  * @param list A SourceFileList created by ohcount_sourcefile_list_new().
 205  * @param directory The directory whose contents are to be added to the list.
 206  */
 207 void ohcount_sourcefile_list_add_directory(SourceFileList *list,
 208                                            const char *directory);
 209
 210 /**
 211  * Returns a new LocList for all files in the given SourceFileList.
 212  * @param list A SourceFileList created by ohcount_sourcefile_list_new().
 213  * @return LocList
 214  */
 215 LocList *ohcount_sourcefile_list_analyze_languages(SourceFileList *list);
 216
 217 /**
 218  * Frees the memory allocated for a given SourceFileList.
 219  * @param list A SourceFileList created by ohcount_sourcefile_list_new().
 220  */
 221 void ohcount_sourcefile_list_free(SourceFileList *list);
 222
 223 #endif