1 /* SPDX-License-Identifier: Zlib */ 2 3 #ifndef GIRARA_UTILS_H 4 #define GIRARA_UTILS_H 5 6 #include <stdio.h> 7 8 #include "types.h" 9 #include "macros.h" 10 #include "log.h" 11 12 /** 13 * Enum for directories specified in the XDG specification. 14 */ 15 typedef enum { 16 XDG_CONFIG, /**< XDG_CONFIG_HOME */ 17 XDG_DATA, /**< XDG_DATA_HOME */ 18 XDG_CONFIG_DIRS, /**< XDG_CONFIG_DIRS */ 19 XDG_DATA_DIRS, /**< XDG_DATA_DIRS */ 20 XDG_CACHE, /**< XDG_CACHE_HOME */ 21 } girara_xdg_path_t; 22 23 /** 24 * Returns the home directory for the given user. $HOME is preferred over the 25 * value from g_get_home_dir. 26 * 27 * @param user a username or NULL to get home directory of the current user. 28 * @return a string containing the path to the user's home directory (needs to 29 * be freed with g_free) or NULL if the user doesn't exist. 30 */ 31 char* girara_get_home_directory(const char* user) GIRARA_VISIBLE; 32 33 /** 34 * Returns a specific path specified in the XDG specification. ~ in paths will 35 * not be expanded. 36 * @param path which path to get 37 * @return a string containing the requested patch (needs to be freed with 38 * g_free) or NULL for invalid values. 39 */ 40 char* girara_get_xdg_path(girara_xdg_path_t path) GIRARA_VISIBLE; 41 42 /** 43 * Opens a URI with xdg-open. If xdg-open is not available, it falls back to the equivalent of gio 44 * open. 45 * 46 * @param uri the URI to be opened. 47 * @return true on success, false otherwise 48 */ 49 bool girara_xdg_open(const char* uri) GIRARA_VISIBLE; 50 51 /** 52 * Opens a URI with xdg-open in a different working directory. If xdg-open is not available, it 53 * falls back to the equivalent of gio open. 54 * 55 * @param uri the URI to be opened. 56 * @param working_directory working directory 57 * @return true on success, false otherwise 58 */ 59 bool girara_xdg_open_with_working_directory(const char* uri, const char* working_directory) GIRARA_VISIBLE; 60 61 /** 62 * Splits paths separated by : (as in $PATH) into a list. 63 * 64 * @param patharray String like $PATH to split 65 * @return a list of paths and NULL on failure. 66 */ 67 girara_list_t* girara_split_path_array(const char* patharray) GIRARA_VISIBLE; 68 69 /** 70 * Returns a "fixed" version of path. Which means, it will be an absolute path 71 * and fully expanded. ~ and ~user will be replaced by the current user's home 72 * directory (user's home directory respectively). 73 * @param path the path to "fix". 74 * @return the "fixed" path (needs to be freed with g_free). 75 */ 76 char* girara_fix_path(const char* path) GIRARA_VISIBLE; 77 78 /** 79 * Open a file in a safe way 80 * 81 * @param path Path of the file 82 * @param mode Mode that the file should be opened 83 * @return NULL if an error occurred 84 */ 85 FILE* girara_file_open(const char* path, const char* mode) GIRARA_VISIBLE; 86 87 /** 88 * Reads a line from the file. The returned string has to be released with 89 * g_free. 90 * 91 * @param file The file stream 92 * @return Read line or NULL if an error occurred 93 */ 94 char* girara_file_read_line(FILE* file) GIRARA_VISIBLE; 95 96 /** 97 * Reads the whole content from a file. Returned string has to be freed. 98 * 99 * @param path Path to the file 100 * @return Read file or NULL if an error occurred 101 */ 102 char* girara_file_read(const char* path) GIRARA_VISIBLE; 103 104 /** 105 * Reads the whole content from a file. Returned string has to be freed. 106 * 107 * @param file file to read 108 * @return Read file or NULL if an error occurred 109 */ 110 char* girara_file_read2(FILE* file) GIRARA_VISIBLE; 111 112 /** 113 * Trims and cleans a line from multiple whitespaces 114 * 115 * @param line 116 */ 117 void girara_clean_line(char* line) GIRARA_VISIBLE; 118 119 /** 120 * Changes the size of the memory block by wrapping a realloc function call 121 * In addition it frees the old memory block if realloc fails. 122 * 123 * @param ptr Memory space 124 * @param size Number of bytes 125 * @return Pointer to the allocated memory block or NULL 126 */ 127 void* girara_safe_realloc(void** ptr, size_t size) GIRARA_ALLOC_SIZE(2) GIRARA_VISIBLE; 128 129 /** 130 * Escape \\, \\t, ", ' and spaces in strings. 131 * @param value The string to be escaped. 132 * @returns The escaped string. Needs to be freed with g_free. 133 */ 134 char* girara_escape_string(const char* value) GIRARA_VISIBLE; 135 136 /** 137 * Replaces all occurrences of old in string with new and returns 138 * a new allocated string 139 * 140 * @param string The original string 141 * @param old String to replace 142 * @param new Replacement string 143 * 144 * @return new allocated string, needs to be freed with g_free 145 */ 146 char* girara_replace_substring(const char* string, const char* old, const char* new) GIRARA_VISIBLE; 147 148 /** 149 * Execute command from argument list 150 * 151 * @param session The used girara session 152 * @param argument_list The argument list 153 * @return true if no error occurred 154 */ 155 bool girara_exec_with_argument_list(girara_session_t* session, girara_list_t* argument_list) GIRARA_VISIBLE; 156 157 /** 158 * Return version of girara. 159 * 160 * @return version string 161 */ 162 const char* girara_version(void) GIRARA_VISIBLE; 163 164 #endif 165