Module cFilesystem
Static methods for dealing with the file-system .
#
Functions
| get_path_parts (file_path) | split path into parts, seperated by slashes important - folders should end with a slash note: this is a virtual function which doesn't require I/O access |
| get_raw_filename (file_path) | provided with a complete path, returns just the filename (no extension) note: this is a virtual function which doesn't require I/O access |
| is_root_folder (str) | check if the given string indicates a root folder note: a root folder is considered "/" on unix-based systems, and [drive letter]:/ on windows systems note: this is a virtual function which doesn't require I/O access |
| get_parent_directory (file_path) | provided with a string, this method will find the parent folder note: returned string is using unix slashes note: this is a virtual function which doesn't require I/O access |
| copy_folder (src_path, dest_path, file_ext, level) | Recursively copy folder |
| ensure_unique_filename (file_path) | if file already exist, return a name with (number) appended to it |
| get_directories (file_path) | break a string into directories note: this is a virtual function which doesn't require I/O access |
| makedir (file_path) | create a whole folder structure in one go (unlike the standard os.mkdir, which is limited to a single folder) |
| rename (old_f, new_f) | rename a file or folder |
| rmdir (folder_path) | on non-posix systems (windows), you can't remove a folder which is not empty - this method will iterate through and delete all files/folders |
| validate_filename (file_path) | make sure a file/folder name does not contain anything considered bad (such as special characters or preceding ./ dot-slash combinations) |
| unixslashes (file_path) | convert windows-style paths to unix-style also: remove doubleslashes |
| sanitize_filename (file_path) | remove illegal characters (similar to validate, but attempts to fix) |
| file_add_extension (file_path, extension) | add file extension (if it hasn't already got it) |
| file_strip_extension (file_path, extension) | remove file extension (if present and matching) |
| assert_string (str, str_name) | so widely used it got it's own function |
| load_string (file_path) | load string from disk |
| list_files (str_path, file_ext, include_path) | list files in a given folder |
| write_string_to_file (file_path, str) | save string to disk |
| copy_file (file_in, file_out) | this will work for small files, but is not recommended on larger ones |
| recurse (str_path, callback_fn, file_ext, level) | Iterate through files and folders and invoke a callback function for each entry |
Functions
- get_path_parts (file_path)
-
split path into parts, seperated by slashes
important - folders should end with a slash
note: this is a virtual function which doesn't require I/O access
Parameters:
- file_path (string)
Returns:
- string, folder
- string, filename
- string, extension
- get_raw_filename (file_path)
-
provided with a complete path, returns just the filename (no extension)
note: this is a virtual function which doesn't require I/O access
Parameters:
- file_path (string)
Returns:
-
string or nil
- is_root_folder (str)
-
check if the given string indicates a root folder
note: a root folder is considered "/" on unix-based systems, and
[drive letter]:/ on windows systems
note: this is a virtual function which doesn't require I/O access
Parameters:
- str
- get_parent_directory (file_path)
-
provided with a string, this method will find the parent folder
note: returned string is using unix slashes
note: this is a virtual function which doesn't require I/O access
Parameters:
- file_path (string)
Returns:
- string or nil if failed
- int, error code
- copy_folder (src_path, dest_path, file_ext, level)
-
Recursively copy folder
Parameters:
- src_path (string)
- dest_path (string)
- file_ext ] (table), whitelisted file extensions, e.g. {"*.bmp"}
- level (int), how many levels to recurse (undefined or 0 is unlimited)
- ensure_unique_filename (file_path)
-
if file already exist, return a name with (number) appended to it
Parameters:
- file_path (string)
- get_directories (file_path)
-
break a string into directories
note: this is a virtual function which doesn't require I/O access
Parameters:
- file_path (string)
Returns:
-
table
- makedir (file_path)
-
create a whole folder structure in one go
(unlike the standard os.mkdir, which is limited to a single folder)
Parameters:
- file_path (string)
Returns:
- bool, true when folder(s) were created
- string, error message when failed
- rename (old_f, new_f)
-
rename a file or folder
Parameters:
- old_f (string)
- new_f (string) TODO @param options (table) "replace" - for existing files/folders "merge" - for existing folders
- rmdir (folder_path)
-
on non-posix systems (windows), you can't remove a folder which is not
empty - this method will iterate through and delete all files/folders
Parameters:
- folder_path (string)
Returns:
- bool, true when folder was removed
- string, error message when failed
- validate_filename (file_path)
-
make sure a file/folder name does not contain anything considered bad
(such as special characters or preceding ./ dot-slash combinations)
Parameters:
- file_path (string)
Returns:
-
bool,string
- unixslashes (file_path)
-
convert windows-style paths to unix-style
also: remove doubleslashes
Parameters:
- file_path (string)
Returns:
-
string
- sanitize_filename (file_path)
-
remove illegal characters (similar to validate, but attempts to fix)
Parameters:
- file_path (string)
Returns:
-
string
- file_add_extension (file_path, extension)
-
add file extension (if it hasn't already got it)
Parameters:
- file_path (string)
- extension (string)
Returns:
-
string
- file_strip_extension (file_path, extension)
-
remove file extension (if present and matching)
Parameters:
- file_path (string)
- extension (string)
Returns:
-
string
- assert_string (str, str_name)
-
so widely used it got it's own function
Parameters:
- str
- str_name
- load_string (file_path)
-
load string from disk
Parameters:
- file_path
- list_files (str_path, file_ext, include_path)
-
list files in a given folder
Parameters:
- str_path (string)
- file_ext (table), valid file extensions , e.g. {"*.bmp"}
- include_path (bool), when true we append path to string
Returns:
-
table
- write_string_to_file (file_path, str)
-
save string to disk
Parameters:
- file_path (string)
- str (string)
Returns:
- bool, true when successful, false when not
- string, error message when failed
- copy_file (file_in, file_out)
-
this will work for small files, but is not recommended on larger ones
Parameters:
- file_in (string)
- file_out (string)
Returns:
-
boolean,string
- recurse (str_path, callback_fn, file_ext, level)
-
Iterate through files and folders and invoke a callback function for each entry
Parameters:
- str_path (string), path to start recursion
- callback_fn (function) return false to stop recursion
- file_ext ] (table), valid file extensions , e.g. {"*.bmp"}
- level (int), how many levels to recurse (undefined or 0 is unlimited)
Returns:
- boolean, true when finished recursing (including when aborted in callback)
- string, error message when failed (e.g. invalid path)