Cleanup: use doxygen groups for BLI_path_util.h
This commit is contained in:
Campbell Barton
@@ -15,27 +15,219 @@
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Path Queries
|
||||
* \{ */
|
||||
|
||||
/**
|
||||
* 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);`
|
||||
* 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`
|
||||
*
|
||||
* (not used anywhere).
|
||||
* Ignored elements in the path:
|
||||
* - Multiple slashes at any point in the path (including start/end).
|
||||
* - Single '.' in the path: `/./` except for the beginning of the path
|
||||
* where it's used to signify a $PWD relative path.
|
||||
*/
|
||||
void BLI_setenv_if_new(const char *env, const char *val) ATTR_NONNULL(1);
|
||||
bool BLI_path_name_at_index(const char *__restrict path,
|
||||
int index,
|
||||
int *__restrict r_offset,
|
||||
int *__restrict r_len) ATTR_NONNULL(1, 3, 4) ATTR_WARN_UNUSED_RESULT;
|
||||
|
||||
/**
|
||||
* 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.
|
||||
* Return true if the path is a UNC share.
|
||||
*/
|
||||
const char *BLI_getenv(const char *env) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
|
||||
bool BLI_path_is_unc(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
|
||||
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Path Parent Operations
|
||||
* \{ */
|
||||
|
||||
/**
|
||||
* Go back one directory.
|
||||
*
|
||||
* Replaces path with the path of its parent directory, returning true if
|
||||
* it was able to find a parent directory within the path.
|
||||
*
|
||||
* On success, the resulting path will always have a trailing slash.
|
||||
*/
|
||||
bool BLI_path_parent_dir(char *path) ATTR_NONNULL(1);
|
||||
/**
|
||||
* Go back until the directory is found.
|
||||
*
|
||||
* Strips off nonexistent (or non-accessible) sub-directories from the end of `dir`,
|
||||
* leaving the path of the lowest-level directory that does exist and we can read.
|
||||
*/
|
||||
bool BLI_path_parent_dir_until_exists(char *path) ATTR_NONNULL(1);
|
||||
|
||||
/**
|
||||
* In the simple case this is similar to `BLI_path_slash_rfind(dirname)`
|
||||
* however it behaves differently when there are redundant characters:
|
||||
*
|
||||
* `/test///dir/./file`
|
||||
* ^
|
||||
* `/test/dir/subdir//file`
|
||||
* ^
|
||||
* \return The position after the parent paths last character or NULL on failure.
|
||||
* Neither `path` or `&path[path_len - 1]` are ever returned.
|
||||
*/
|
||||
const char *BLI_path_parent_dir_end(const char *path, size_t path_len)
|
||||
ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
|
||||
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Path Make Safe / Sanitize
|
||||
* \{ */
|
||||
|
||||
/**
|
||||
* Make given name safe to be used in paths.
|
||||
*
|
||||
* \param allow_tokens: Permit the usage of '<' and '>' characters. This can be
|
||||
* leveraged by higher layers to support "virtual filenames" which contain
|
||||
* substitution markers delineated between the two characters.
|
||||
*
|
||||
* \return true if \a fname was changed, false otherwise.
|
||||
*
|
||||
* For now, simply replaces reserved chars (as listed in
|
||||
* https://en.wikipedia.org/wiki/Filename#Reserved_characters_and_words )
|
||||
* by underscores ('_').
|
||||
*
|
||||
* \note Space case ' ' is a bit of an edge case here - in theory it is allowed,
|
||||
* but again can be an issue in some cases, so we simply replace it by an underscore too
|
||||
* (good practice anyway).
|
||||
* REMOVED based on popular demand (see #45900).
|
||||
* Percent '%' char is a bit same case - not recommended to use it,
|
||||
* but supported by all decent file-systems/operating-systems around.
|
||||
*
|
||||
* \note On Windows, it also ensures there is no '.' (dot char) at the end of the file,
|
||||
* this can lead to issues.
|
||||
*
|
||||
* \note On Windows, it also checks for forbidden names
|
||||
* (see https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247%28v=vs.85%29.aspx ).
|
||||
*/
|
||||
bool BLI_path_make_safe_filename_ex(char *fname, bool allow_tokens) ATTR_NONNULL(1);
|
||||
bool BLI_path_make_safe_filename(char *fname) ATTR_NONNULL(1);
|
||||
|
||||
/**
|
||||
* Make given path OS-safe.
|
||||
*
|
||||
* \return true if \a path was changed, false otherwise.
|
||||
*/
|
||||
bool BLI_path_make_safe(char *path) ATTR_NONNULL(1);
|
||||
|
||||
/**
|
||||
* Creates a display string from path to be used menus and the user interface.
|
||||
* Like `bpy.path.display_name()`.
|
||||
*/
|
||||
void BLI_path_to_display_name(char *display_name, int display_name_maxncpy, const char *name)
|
||||
ATTR_NONNULL(1, 3);
|
||||
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Path Normalize
|
||||
* \{ */
|
||||
|
||||
/**
|
||||
* Remove redundant characters from \a path.
|
||||
*
|
||||
* The following operations are performed:
|
||||
* - Redundant path components such as `//`, `/./` & `./` (prefix) are stripped.
|
||||
* (with the exception of `//` prefix used for blend-file relative paths).
|
||||
* - `..` are resolved so `<parent>/../<child>/` resolves to `<child>/`.
|
||||
* Note that the resulting path may begin with `..` if it's relative.
|
||||
*
|
||||
* Details:
|
||||
* - The slash direction is expected to be native (see #SEP).
|
||||
* When calculating a canonical paths you may need to run #BLI_path_slash_native first.
|
||||
* #BLI_path_cmp_normalized can be used for canonical path comparison.
|
||||
* - Trailing slashes are left intact (unlike Python which strips them).
|
||||
* - Handling paths beginning with `..` depends on them being absolute or relative.
|
||||
* For absolute paths they are removed (e.g. `/../path` becomes `/path`).
|
||||
* For relative paths they are kept as it's valid to reference paths above a relative location
|
||||
* such as `//../parent` or `../parent`.
|
||||
*
|
||||
* \param path: The path to a file or directory which can be absolute or relative.
|
||||
*/
|
||||
void BLI_path_normalize(char *path) ATTR_NONNULL(1);
|
||||
/**
|
||||
* Cleanup file-path ensuring a trailing slash.
|
||||
*
|
||||
* \note Same as #BLI_path_normalize but adds a trailing slash.
|
||||
*/
|
||||
void BLI_path_normalize_dir(char *dir, size_t dir_maxncpy) ATTR_NONNULL(1);
|
||||
|
||||
#if defined(WIN32)
|
||||
void BLI_path_normalize_unc_16(wchar_t *path_16);
|
||||
void BLI_path_normalize_unc(char *path, int path_maxncpy);
|
||||
#endif
|
||||
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Path FileName Manipulation
|
||||
* \{ */
|
||||
|
||||
/**
|
||||
* 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 filepath_maxncpy, const char *filename)
|
||||
ATTR_NONNULL(1, 3);
|
||||
|
||||
/**
|
||||
* Appends a suffix to the `path`, fitting it before the extension
|
||||
*
|
||||
* path = `Foo.png`, suffix = `123`, separator = `_`.
|
||||
* `Foo.png` -> `Foo_123.png`.
|
||||
*
|
||||
* \param path: original (and final) string.
|
||||
* \param path_maxncpy: Maximum length of path.
|
||||
* \param suffix: String to append to the original path.
|
||||
* \param sep: Optional separator character.
|
||||
* \return true if succeeded.
|
||||
*/
|
||||
bool BLI_path_suffix(char *path, size_t path_maxncpy, const char *suffix, const char *sep)
|
||||
ATTR_NONNULL(1, 3, 4);
|
||||
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Path Slash Utilities
|
||||
* \{ */
|
||||
|
||||
/**
|
||||
* \return pointer to the leftmost path separator in path (or NULL when not found).
|
||||
*/
|
||||
const char *BLI_path_slash_find(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
|
||||
/**
|
||||
* \return pointer to the rightmost path separator in path (or NULL when not found).
|
||||
*/
|
||||
const char *BLI_path_slash_rfind(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
|
||||
/**
|
||||
* Appends a slash to path if there isn't one there already.
|
||||
* Returns the new length of the path.
|
||||
*/
|
||||
int BLI_path_slash_ensure(char *path, size_t path_maxncpy) ATTR_NONNULL(1);
|
||||
/**
|
||||
* Removes the last slash and everything after it to the end of path, if there is one.
|
||||
*/
|
||||
void BLI_path_slash_rstrip(char *path) ATTR_NONNULL(1);
|
||||
/**
|
||||
* Changes to the path separators to the native ones for this OS.
|
||||
*/
|
||||
void BLI_path_slash_native(char *path) ATTR_NONNULL(1);
|
||||
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Path Directory/FileName Split
|
||||
* \{ */
|
||||
|
||||
/**
|
||||
* Copies directory and file components from `filepath` into `dir` and `file`, e.g.
|
||||
@@ -58,17 +250,20 @@ void BLI_path_split_dir_part(const char *filepath, char *dir, size_t dir_maxncpy
|
||||
*/
|
||||
void BLI_path_split_file_part(const char *filepath, char *file, size_t file_maxncpy)
|
||||
ATTR_NONNULL(1, 2);
|
||||
|
||||
/**
|
||||
* Returns a pointer to the last extension (e.g. the position of the last period).
|
||||
* Returns a pointer to the nil byte when no extension is found.
|
||||
* 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_extension_or_end(const char *filepath)
|
||||
ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT ATTR_RETURNS_NONNULL;
|
||||
/**
|
||||
* 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(1) ATTR_WARN_UNUSED_RESULT;
|
||||
const char *BLI_path_basename(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
|
||||
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Path Append
|
||||
* \{ */
|
||||
|
||||
/**
|
||||
* Append a filename to a dir, ensuring slash separates.
|
||||
@@ -83,6 +278,12 @@ size_t BLI_path_append(char *__restrict dst, size_t dst_maxncpy, const char *__r
|
||||
size_t BLI_path_append_dir(char *__restrict dst, size_t dst_maxncpy, const char *__restrict dir)
|
||||
ATTR_NONNULL(1, 3);
|
||||
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Path Join
|
||||
* \{ */
|
||||
|
||||
/**
|
||||
* See #BLI_path_join doc-string.
|
||||
*/
|
||||
@@ -192,65 +393,23 @@ BLI_INLINE size_t _BLI_path_join_12(_BLI_PATH_JOIN_ARGS_10)
|
||||
#undef _BLI_PATH_JOIN_ARGS_9
|
||||
#undef _BLI_PATH_JOIN_ARGS_10
|
||||
|
||||
/**
|
||||
* 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(1) 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`
|
||||
*
|
||||
* Ignored elements in the path:
|
||||
* - Multiple slashes at any point in the path (including start/end).
|
||||
* - Single '.' in the path: `/./` except for the beginning of the path
|
||||
* where it's used to signify a $PWD relative path.
|
||||
*/
|
||||
bool BLI_path_name_at_index(const char *__restrict path,
|
||||
int index,
|
||||
int *__restrict r_offset,
|
||||
int *__restrict r_len) ATTR_NONNULL(1, 3, 4) 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_NONNULL(1, 2) ATTR_WARN_UNUSED_RESULT;
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Path File Extensions
|
||||
* \{ */
|
||||
|
||||
/**
|
||||
* \return pointer to the leftmost path separator in path (or NULL when not found).
|
||||
* Returns a pointer to the last extension (e.g. the position of the last period).
|
||||
* Returns a pointer to the nil byte when no extension is found.
|
||||
*/
|
||||
const char *BLI_path_slash_find(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
|
||||
const char *BLI_path_extension_or_end(const char *filepath)
|
||||
ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT ATTR_RETURNS_NONNULL;
|
||||
/**
|
||||
* \return pointer to the rightmost path separator in path (or NULL when not found).
|
||||
* 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_slash_rfind(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
|
||||
/**
|
||||
* Appends a slash to path if there isn't one there already.
|
||||
* Returns the new length of the path.
|
||||
*/
|
||||
int BLI_path_slash_ensure(char *path, size_t path_maxncpy) ATTR_NONNULL(1);
|
||||
/**
|
||||
* Removes the last slash and everything after it to the end of path, if there is one.
|
||||
*/
|
||||
void BLI_path_slash_rstrip(char *path) ATTR_NONNULL(1);
|
||||
/**
|
||||
* Changes to the path separators to the native ones for this OS.
|
||||
*/
|
||||
void BLI_path_slash_native(char *path) ATTR_NONNULL(1);
|
||||
|
||||
#ifdef _WIN32
|
||||
bool BLI_path_program_extensions_add_win32(char *program_name, size_t program_name_maxncpy);
|
||||
#endif
|
||||
/**
|
||||
* Search for a binary (executable)
|
||||
*/
|
||||
bool BLI_path_program_search(char *program_filepath,
|
||||
size_t program_filepath_maxncpy,
|
||||
const char *program_name) ATTR_NONNULL(1, 3);
|
||||
const char *BLI_path_extension(const char *filepath) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
|
||||
|
||||
/**
|
||||
* \return true when `path` end with `ext` (case insensitive).
|
||||
@@ -295,12 +454,73 @@ bool BLI_path_extension_strip(char *path) ATTR_NONNULL(1);
|
||||
*/
|
||||
bool BLI_path_extension_ensure(char *path, size_t path_maxncpy, const char *ext)
|
||||
ATTR_NONNULL(1, 3);
|
||||
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Path Comparison / Contains
|
||||
* \{ */
|
||||
|
||||
/* Path string comparisons: case-insensitive for Windows, case-sensitive otherwise. */
|
||||
#if defined(WIN32)
|
||||
# define BLI_path_cmp BLI_strcasecmp
|
||||
# define BLI_path_ncmp BLI_strncasecmp
|
||||
#else
|
||||
# define BLI_path_cmp strcmp
|
||||
# define BLI_path_ncmp strncmp
|
||||
#endif
|
||||
|
||||
/**
|
||||
* 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`.
|
||||
* Returns the result of #BLI_path_cmp with both paths normalized and slashes made native.
|
||||
*
|
||||
* \note #BLI_path_cmp is used for Blender's internal logic to consider paths to be the same
|
||||
* #BLI_path_cmp_normalized may be used in when handling other kinds of paths
|
||||
* (e.g. importers/exporters) but should be used consistently.
|
||||
*
|
||||
* Checking the normalized paths is not a guarantee the paths reference different files.
|
||||
* An equivalent to Python's `os.path.samefile` could be supported for checking if paths
|
||||
* point to the same location on the file-system (following symbolic-links).
|
||||
*/
|
||||
bool BLI_path_filename_ensure(char *filepath, size_t filepath_maxncpy, const char *filename)
|
||||
ATTR_NONNULL(1, 3);
|
||||
int BLI_path_cmp_normalized(const char *p1, const char *p2)
|
||||
ATTR_NONNULL(1, 2) 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_NONNULL(1, 2) ATTR_WARN_UNUSED_RESULT;
|
||||
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Program Specific Path Functions
|
||||
* \{ */
|
||||
|
||||
#ifdef _WIN32
|
||||
bool BLI_path_program_extensions_add_win32(char *program_name, size_t program_name_maxncpy);
|
||||
#endif
|
||||
/**
|
||||
* Search for a binary (executable)
|
||||
*/
|
||||
bool BLI_path_program_search(char *program_filepath,
|
||||
size_t program_filepath_maxncpy,
|
||||
const char *program_name) ATTR_NONNULL(1, 3);
|
||||
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Blender Specific Frame Sequence Encode/Decode
|
||||
* \{ */
|
||||
|
||||
/**
|
||||
* Returns in area pointed to by `path` a string of the form `<head><pic><tail>`,
|
||||
* where pic is formatted as `numlen` digits with leading zeroes.
|
||||
*/
|
||||
void BLI_path_sequence_encode(char *path,
|
||||
size_t path_maxncpy,
|
||||
const char *head,
|
||||
const char *tail,
|
||||
unsigned short numlen,
|
||||
int pic);
|
||||
|
||||
/**
|
||||
* Looks for a sequence of decimal digits in `path`, preceding any filename extension,
|
||||
* returning the integer value if found, or 0 if not.
|
||||
@@ -318,112 +538,12 @@ int BLI_path_sequence_decode(const char *path,
|
||||
char *tail,
|
||||
size_t tail_maxncpy,
|
||||
unsigned short *r_digits_len);
|
||||
/**
|
||||
* Returns in area pointed to by `path` a string of the form `<head><pic><tail>`,
|
||||
* where pic is formatted as `numlen` digits with leading zeroes.
|
||||
*/
|
||||
void BLI_path_sequence_encode(char *path,
|
||||
size_t path_maxncpy,
|
||||
const char *head,
|
||||
const char *tail,
|
||||
unsigned short numlen,
|
||||
int pic);
|
||||
|
||||
/**
|
||||
* Remove redundant characters from \a path.
|
||||
*
|
||||
* The following operations are performed:
|
||||
* - Redundant path components such as `//`, `/./` & `./` (prefix) are stripped.
|
||||
* (with the exception of `//` prefix used for blend-file relative paths).
|
||||
* - `..` are resolved so `<parent>/../<child>/` resolves to `<child>/`.
|
||||
* Note that the resulting path may begin with `..` if it's relative.
|
||||
*
|
||||
* Details:
|
||||
* - The slash direction is expected to be native (see #SEP).
|
||||
* When calculating a canonical paths you may need to run #BLI_path_slash_native first.
|
||||
* #BLI_path_cmp_normalized can be used for canonical path comparison.
|
||||
* - Trailing slashes are left intact (unlike Python which strips them).
|
||||
* - Handling paths beginning with `..` depends on them being absolute or relative.
|
||||
* For absolute paths they are removed (e.g. `/../path` becomes `/path`).
|
||||
* For relative paths they are kept as it's valid to reference paths above a relative location
|
||||
* such as `//../parent` or `../parent`.
|
||||
*
|
||||
* \param path: The path to a file or directory which can be absolute or relative.
|
||||
*/
|
||||
void BLI_path_normalize(char *path) ATTR_NONNULL(1);
|
||||
/**
|
||||
* Cleanup file-path ensuring a trailing slash.
|
||||
*
|
||||
* \note Same as #BLI_path_normalize but adds a trailing slash.
|
||||
*/
|
||||
void BLI_path_normalize_dir(char *dir, size_t dir_maxncpy) ATTR_NONNULL(1);
|
||||
/** \} */
|
||||
|
||||
/**
|
||||
* Make given name safe to be used in paths.
|
||||
*
|
||||
* \param allow_tokens: Permit the usage of '<' and '>' characters. This can be
|
||||
* leveraged by higher layers to support "virtual filenames" which contain
|
||||
* substitution markers delineated between the two characters.
|
||||
*
|
||||
* \return true if \a fname was changed, false otherwise.
|
||||
*
|
||||
* For now, simply replaces reserved chars (as listed in
|
||||
* https://en.wikipedia.org/wiki/Filename#Reserved_characters_and_words )
|
||||
* by underscores ('_').
|
||||
*
|
||||
* \note Space case ' ' is a bit of an edge case here - in theory it is allowed,
|
||||
* but again can be an issue in some cases, so we simply replace it by an underscore too
|
||||
* (good practice anyway).
|
||||
* REMOVED based on popular demand (see #45900).
|
||||
* Percent '%' char is a bit same case - not recommended to use it,
|
||||
* but supported by all decent file-systems/operating-systems around.
|
||||
*
|
||||
* \note On Windows, it also ensures there is no '.' (dot char) at the end of the file,
|
||||
* this can lead to issues.
|
||||
*
|
||||
* \note On Windows, it also checks for forbidden names
|
||||
* (see https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247%28v=vs.85%29.aspx ).
|
||||
*/
|
||||
bool BLI_path_make_safe_filename_ex(char *fname, bool allow_tokens) ATTR_NONNULL(1);
|
||||
bool BLI_path_make_safe_filename(char *fname) ATTR_NONNULL(1);
|
||||
|
||||
/**
|
||||
* Make given path OS-safe.
|
||||
*
|
||||
* \return true if \a path was changed, false otherwise.
|
||||
*/
|
||||
bool BLI_path_make_safe(char *path) ATTR_NONNULL(1);
|
||||
|
||||
/**
|
||||
* Go back one directory.
|
||||
*
|
||||
* Replaces path with the path of its parent directory, returning true if
|
||||
* it was able to find a parent directory within the path.
|
||||
*
|
||||
* On success, the resulting path will always have a trailing slash.
|
||||
*/
|
||||
bool BLI_path_parent_dir(char *path) ATTR_NONNULL(1);
|
||||
/**
|
||||
* Go back until the directory is found.
|
||||
*
|
||||
* Strips off nonexistent (or non-accessible) sub-directories from the end of `dir`,
|
||||
* leaving the path of the lowest-level directory that does exist and we can read.
|
||||
*/
|
||||
bool BLI_path_parent_dir_until_exists(char *path) ATTR_NONNULL(1);
|
||||
|
||||
/**
|
||||
* In the simple case this is similar to `BLI_path_slash_rfind(dirname)`
|
||||
* however it behaves differently when there are redundant characters:
|
||||
*
|
||||
* `/test///dir/./file`
|
||||
* ^
|
||||
* `/test/dir/subdir//file`
|
||||
* ^
|
||||
* \return The position after the parent paths last character or NULL on failure.
|
||||
* Neither `path` or `&path[path_len - 1]` are ever returned.
|
||||
*/
|
||||
const char *BLI_path_parent_dir_end(const char *path, size_t path_len)
|
||||
ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Blender Specific Frame Number Apply/Strip
|
||||
* \{ */
|
||||
|
||||
/**
|
||||
* Replaces "#" character sequence in last slash-separated component of `path`
|
||||
@@ -452,78 +572,11 @@ void BLI_path_frame_strip(char *path, char *r_ext, size_t ext_maxncpy) ATTR_NONN
|
||||
* Check if we have '#' chars, usable for #BLI_path_frame, #BLI_path_frame_range
|
||||
*/
|
||||
bool BLI_path_frame_check_chars(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
|
||||
/**
|
||||
* Checks for a relative path (ignoring Blender's "//") prefix
|
||||
* (unlike `!BLI_path_is_rel(path)`).
|
||||
* When false, #BLI_path_abs_from_cwd would expand the absolute path.
|
||||
*/
|
||||
bool BLI_path_is_abs_from_cwd(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
|
||||
/**
|
||||
* Checks for relative path, expanding them relative to the current working directory.
|
||||
* \returns true if the expansion was performed.
|
||||
*
|
||||
* \note Should only be called with command line paths.
|
||||
* This is _not_ something Blender's internal paths support, instead they use the "//" prefix.
|
||||
* In most cases #BLI_path_abs should be used instead.
|
||||
*/
|
||||
bool BLI_path_abs_from_cwd(char *path, size_t path_maxncpy) ATTR_NONNULL(1);
|
||||
/**
|
||||
* Return true if the path is a UNC share.
|
||||
*/
|
||||
bool BLI_path_is_unc(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
|
||||
|
||||
/**
|
||||
* Creates a display string from path to be used menus and the user interface.
|
||||
* Like `bpy.path.display_name()`.
|
||||
*/
|
||||
void BLI_path_to_display_name(char *display_name, int display_name_maxncpy, const char *name)
|
||||
ATTR_NONNULL(1, 3);
|
||||
|
||||
#if defined(WIN32)
|
||||
void BLI_path_normalize_unc_16(wchar_t *path_16);
|
||||
void BLI_path_normalize_unc(char *path, int path_maxncpy);
|
||||
#endif
|
||||
|
||||
/**
|
||||
* Appends a suffix to the `path`, fitting it before the extension
|
||||
*
|
||||
* path = `Foo.png`, suffix = `123`, separator = `_`.
|
||||
* `Foo.png` -> `Foo_123.png`.
|
||||
*
|
||||
* \param path: original (and final) string.
|
||||
* \param path_maxncpy: Maximum length of path.
|
||||
* \param suffix: String to append to the original path.
|
||||
* \param sep: Optional separator character.
|
||||
* \return true if succeeded.
|
||||
*/
|
||||
bool BLI_path_suffix(char *path, size_t path_maxncpy, const char *suffix, const char *sep)
|
||||
ATTR_NONNULL(1, 3, 4);
|
||||
|
||||
/* Path string comparisons: case-insensitive for Windows, case-sensitive otherwise. */
|
||||
#if defined(WIN32)
|
||||
# define BLI_path_cmp BLI_strcasecmp
|
||||
# define BLI_path_ncmp BLI_strncasecmp
|
||||
#else
|
||||
# define BLI_path_cmp strcmp
|
||||
# define BLI_path_ncmp strncmp
|
||||
#endif
|
||||
|
||||
/**
|
||||
* Returns the result of #BLI_path_cmp with both paths normalized and slashes made native.
|
||||
*
|
||||
* \note #BLI_path_cmp is used for Blender's internal logic to consider paths to be the same
|
||||
* #BLI_path_cmp_normalized may be used in when handling other kinds of paths
|
||||
* (e.g. importers/exporters) but should be used consistently.
|
||||
*
|
||||
* Checking the normalized paths is not a guarantee the paths reference different files.
|
||||
* An equivalent to Python's `os.path.samefile` could be supported for checking if paths
|
||||
* point to the same location on the file-system (following symbolic-links).
|
||||
*/
|
||||
int BLI_path_cmp_normalized(const char *p1, const char *p2)
|
||||
ATTR_NONNULL(1, 2) ATTR_WARN_UNUSED_RESULT;
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Blend File Relative Paths
|
||||
/** \name Blender Spesific File Relative Paths
|
||||
* \{ */
|
||||
|
||||
/**
|
||||
@@ -571,6 +624,32 @@ bool BLI_path_is_rel(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
|
||||
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Current Working Directory Specific Paths
|
||||
* \{ */
|
||||
|
||||
/**
|
||||
* Checks for a relative path (ignoring Blender's "//") prefix
|
||||
* (unlike `!BLI_path_is_rel(path)`).
|
||||
* When false, #BLI_path_abs_from_cwd would expand the absolute path.
|
||||
*/
|
||||
bool BLI_path_is_abs_from_cwd(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
|
||||
/**
|
||||
* Checks for relative path, expanding them relative to the current working directory.
|
||||
* \returns true if the expansion was performed.
|
||||
*
|
||||
* \note Should only be called with command line paths.
|
||||
* This is _not_ something Blender's internal paths support, instead they use the "//" prefix.
|
||||
* In most cases #BLI_path_abs should be used instead.
|
||||
*/
|
||||
bool BLI_path_abs_from_cwd(char *path, size_t path_maxncpy) ATTR_NONNULL(1);
|
||||
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Native Slash Defines & Checks
|
||||
* \{ */
|
||||
|
||||
#ifdef WIN32
|
||||
# define SEP '\\'
|
||||
# define ALTSEP '/'
|
||||
@@ -601,6 +680,42 @@ BLI_INLINE bool BLI_path_slash_is_native_compat(const char ch)
|
||||
return false;
|
||||
}
|
||||
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name OS Level Wrappers
|
||||
*
|
||||
* TODO: move these to a different module, they are not path functions.
|
||||
* \{ */
|
||||
|
||||
/**
|
||||
* 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) ATTR_WARN_UNUSED_RESULT;
|
||||
|
||||
/** \} */
|
||||
|
||||
/* -------------------------------------------------------------------- */
|
||||
/** \name Current & Parent Directory Defines/Macros
|
||||
* \{ */
|
||||
|
||||
/* Parent and current dir helpers. */
|
||||
#define FILENAME_PARENT ".."
|
||||
#define FILENAME_CURRENT "."
|
||||
@@ -611,6 +726,8 @@ BLI_INLINE bool BLI_path_slash_is_native_compat(const char ch)
|
||||
#define FILENAME_IS_CURRPAR(_n) \
|
||||
(((_n)[0] == '.') && (((_n)[1] == '\0') || (((_n)[1] == '.') && ((_n)[2] == '\0'))))
|
||||
|
||||
/** \} */
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
Reference in New Issue
Block a user