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 copied and may be 'free'd immediately.
  55  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
  56  * @param language The language to set the SourceFile to.
  57  */
  58 void ohcount_sourcefile_set_language(SourceFile *sourcefile,
  59                                      const char *language);
  60
  61 /**
  62  * Returns the detected language of a given SourceFile.
  63  * The returned pointer is used internally and may not be 'free'd.
  64  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
  65  * @return string language name.
  66  */
  67 const char *ohcount_sourcefile_get_language(SourceFile *sourcefile);
  68
  69 /**
  70  * Parses the given SourceFile with the default callback that keeps track of the
  71  * number of lines of code, comments, and blank lines.
  72  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
  73  */
  74 void ohcount_sourcefile_parse(SourceFile *sourcefile);
  75
  76 /**
  77  * Returns the ParsedLanguageList parsed out of the given SourceFile.
  78  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
  79  * @return ParsedLanguageList
  80  */
  81 ParsedLanguageList *ohcount_sourcefile_get_parsed_language_list(SourceFile
  82                                                                 *sourcefile);
  83
  84 /**
  85  * Parses the given SourceFile with a specific callback.
  86  * The callback is called for each line parsed, not entity.
  87  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
  88  * @param callback The callback function to call for every line parsed.
  89  * @param userdata Userdata to pass to the callback function.
  90  */
  91 void ohcount_sourcefile_parse_with_callback(SourceFile *sourcefile,
  92                                             void (*callback) (const char *,
  93                                                               const char *, int,
  94                                                               int, void *),
  95                                             void *userdata);
  96
  97 /**
  98  * Parses the given SourceFile with a specific callback.
  99  * The callback is called for each entity parsed, not line.
 100  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
 101  * @param callback The callback function to call for every entity parsed.
 102  * @param userdata Userdata to pass to the callback function.
 103  */
 104 void ohcount_sourcefile_parse_entities_with_callback(SourceFile *sourcefile,
 105                                                      void (*callback)
 106                                                        (const char *,
 107                                                         const char *, int,
 108                                                         int, void *),
 109                                                      void *userdata);
 110
 111 /**
 112  * Returns a LicenseList of detected licenses in the given SourceFile.
 113  * The returned list and its contents are used internally and may not be
 114  * 'free'd.
 115  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
 116  * @return LicenseList
 117  */
 118 LicenseList *ohcount_sourcefile_get_license_list(SourceFile *sourcefile);
 119
 120 /**
 121  * Returns a LocList of total lines of code in each language in the given
 122  * SourceFile.
 123  * The returned list and its contents are used internally and may not be
 124  * 'free'd.
 125  * @param sourcefile A SourceFile created by ohcount_sourcefile_new().
 126  * @return LocList
 127  */
 128 LocList *ohcount_sourcefile_get_loc_list(SourceFile *sourcefile);
 129
 130 /**
 131  * Returns a LocDeltaList reflecting the changes from one revision of a
 132  * SourceFile to another for all languages.
 133  * The returned pointer must be 'free'd.
 134  * @param from The reference SourceFile created by ohcount_sourcefile_new().
 135  * @param to The SourceFile to compare the reference SourceFile to (typically a
 136  *   later revision instead of a completely different SourceFile).
 137  * @return LocDeltaList
 138  */
 139 LocDeltaList *ohcount_sourcefile_diff(SourceFile *from, SourceFile *to);
 140
 141 /**
 142  * Returns a LocDelta reflecting the changes from one revision of a SourceFile
 143  * to another for a given language.
 144  * The given language is not copied and may not be 'free'd. Use a language
 145  * defined in src/languages.h.
 146  * The returned pointer must be 'free'd.
 147  * @param from The reference SourceFile created by ohcount_sourcefile_new().
 148  * @param language The language to calculate the LocDelta from.
 149  * @param to The SourceFile to compare the reference SourceFile to (typically a
 150  *   later revision instead of a completely different SourceFile).
 151  * @return LocDelta
 152  */
 153 LocDelta *ohcount_sourcefile_calc_loc_delta(SourceFile *from,
 154                                             const char *language,
 155                                             SourceFile *to);
 156
 157 /**
 158  * Sets the given SourceFile's directory contents to the string array given.
 159  * The given array is copied and may be 'free'd immediately.
 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