/* * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software Foundation, * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV. * All rights reserved. */ #pragma once /** \file * \ingroup bli */ #include "BLI_compiler_attrs.h" #include "BLI_utildefines.h" #ifdef __cplusplus extern "C" { #endif /** * Sets the specified environment variable to the specified value, * and clears it if `val == NULL`. */ void BLI_setenv(const char *env, const char *val) ATTR_NONNULL(1); /** * Only set an environment variable if already not there. * Like Unix `setenv(env, val, 0);` * * (not used anywhere). */ void BLI_setenv_if_new(const char *env, const char *val) ATTR_NONNULL(1); /** * Get an environment variable, result has to be used immediately. * * On windows #getenv gets its variables from a static copy of the environment variables taken at * process start-up, causing it to not pick up on environment variables created during runtime. * This function uses an alternative method to get environment variables that does pick up on * runtime environment variables. The result will be UTF-8 encoded. */ const char *BLI_getenv(const char *env) ATTR_NONNULL(1); /** * Returns in `string` the concatenation of `dir` and `file` (also with `relabase` on the * front if specified and `dir` begins with "//"). Normalizes all occurrences of path * separators, including ensuring there is exactly one between the copies of `dir` and `file`, * and between the copies of `relabase` and `dir`. * * \param relabase: Optional prefix to substitute for "//" on front of `dir`. * \param string: Area to return result. */ void BLI_make_file_string(const char *relabase, char *string, const char *dir, const char *file); /** * Ensures that the parent directory of `name` exists. * * \return true on success (i.e. given path now exists on file-system), false otherwise. */ bool BLI_make_existing_file(const char *name); /** * Converts `/foo/bar.txt` to `/foo/` and `bar.txt` * * - Won't change \a string. * - Won't create any directories. * - Doesn't use CWD, or deal with relative paths. * - Only fill's in \a dir and \a file when they are non NULL. */ void BLI_split_dirfile( const char *string, char *dir, char *file, const size_t dirlen, const size_t filelen); /** * Copies the parent directory part of string into `dir`, max length `dirlen`. */ void BLI_split_dir_part(const char *string, char *dir, const size_t dirlen); /** * Copies the leaf filename part of string into `file`, max length `filelen`. */ void BLI_split_file_part(const char *string, char *file, const size_t filelen); /** * Returns a pointer to the last extension (e.g. the position of the last period). * Returns NULL if there is no extension. */ const char *BLI_path_extension(const char *filepath) ATTR_NONNULL(); /** * Append a filename to a dir, ensuring slash separates. */ void BLI_path_append(char *__restrict dst, const size_t maxlen, const char *__restrict file) ATTR_NONNULL(); /** * Simple appending of filename to dir, does not check for valid path! * Puts result into `dst`, which may be same area as `dir`. * * \note Consider using #BLI_path_join for more general path joining * that de-duplicates separators and can handle an arbitrary number of paths. */ void BLI_join_dirfile(char *__restrict dst, const size_t maxlen, const char *__restrict dir, const char *__restrict file) ATTR_NONNULL(); /** * Join multiple strings into a path, ensuring only a single path separator between each, * and trailing slash is kept. * * \note If you want a trailing slash, add `SEP_STR` as the last path argument, * duplicate slashes will be cleaned up. */ size_t BLI_path_join(char *__restrict dst, const size_t dst_len, const char *path_first, ...) ATTR_NONNULL(1, 3) ATTR_SENTINEL(0); /** * Like Python's `os.path.basename()` * * \return The pointer into \a path string immediately after last slash, * or start of \a path if none found. */ const char *BLI_path_basename(const char *path) ATTR_NONNULL() ATTR_WARN_UNUSED_RESULT; /** * Get an element of the path at an index, eg: * "/some/path/file.txt" where an index of: * - 0 or -3: "some" * - 1 or -2: "path" * - 2 or -1: "file.txt" * * Ignores multiple slashes at any point in the path (including start/end). */ bool BLI_path_name_at_index(const char *__restrict path, int index, int *__restrict r_offset, int *__restrict r_len) ATTR_NONNULL() ATTR_WARN_UNUSED_RESULT; /** Return true only if #containee_path is contained in #container_path. */ bool BLI_path_contains(const char *container_path, const char *containee_path) ATTR_WARN_UNUSED_RESULT; /** * \return pointer to the leftmost path separator in string (or NULL when not found). */ const char *BLI_path_slash_find(const char *string) ATTR_NONNULL() ATTR_WARN_UNUSED_RESULT; /** * \return pointer to the rightmost path separator in string (or NULL when not found). */ const char *BLI_path_slash_rfind(const char *string) ATTR_NONNULL() ATTR_WARN_UNUSED_RESULT; /** * Appends a slash to string if there isn't one there already. * Returns the new length of the string. */ int BLI_path_slash_ensure(char *string) ATTR_NONNULL(); /** * Removes the last slash and everything after it to the end of string, if there is one. */ void BLI_path_slash_rstrip(char *string) ATTR_NONNULL(); /** * Changes to the path separators to the native ones for this OS. */ void BLI_path_slash_native(char *path) ATTR_NONNULL(); #ifdef _WIN32 bool BLI_path_program_extensions_add_win32(char *name, const size_t maxlen); #endif /** * Search for a binary (executable) */ bool BLI_path_program_search(char *fullname, const size_t maxlen, const char *name); /** * \return true when `str` end with `ext` (case insensitive). */ bool BLI_path_extension_check(const char *str, const char *ext) ATTR_NONNULL() ATTR_WARN_UNUSED_RESULT; bool BLI_path_extension_check_n(const char *str, ...) ATTR_NONNULL(1) ATTR_SENTINEL(0); /** * \return true when `str` ends with any of the suffixes in `ext_array`. */ bool BLI_path_extension_check_array(const char *str, const char **ext_array) ATTR_NONNULL() ATTR_WARN_UNUSED_RESULT; /** * Semicolon separated wildcards, eg: `*.zip;*.py;*.exe` * does `str` match any of the semicolon-separated glob patterns in #fnmatch. */ bool BLI_path_extension_check_glob(const char *str, const char *ext_fnmatch) ATTR_NONNULL() ATTR_WARN_UNUSED_RESULT; /** * Does basic validation of the given glob string, to prevent common issues from string * truncation. * * For now, only forbids last group to be a wildcard-only one, if there are more than one group * (i.e. things like `*.txt;*.cpp;*` are changed to `*.txt;*.cpp;`) * * \returns true if it had to modify given \a ext_fnmatch pattern. */ bool BLI_path_extension_glob_validate(char *ext_fnmatch) ATTR_NONNULL(); /** * Removes any existing extension on the end of \a path and appends \a ext. * \return false if there was no room. */ bool BLI_path_extension_replace(char *path, size_t maxlen, const char *ext) ATTR_NONNULL(); /** * Strip's trailing '.'s and adds the extension only when needed */ bool BLI_path_extension_ensure(char *path, size_t maxlen, const char *ext) ATTR_NONNULL(); /** * Ensure `filepath` has a file component, adding `filename` when it's empty or ends with a slash. * \return true if the `filename` was appended to `filepath`. */ bool BLI_path_filename_ensure(char *filepath, size_t maxlen, const char *filename) ATTR_NONNULL(); /** * Looks for a sequence of decimal digits in string, preceding any filename extension, * returning the integer value if found, or 0 if not. * * \param string: String to scan. * \param head: Optional area to return copy of part of string prior to digits, * or before dot if no digits. * \param tail: Optional area to return copy of part of string following digits, * or from dot if no digits. * \param r_num_len: Optional to return number of digits found. */ int BLI_path_sequence_decode(const char *string, char *head, char *tail, unsigned short *r_num_len); /** * Returns in area pointed to by string a string of the form `