📂 fs

fs::cat

Print the content of a file to stdout. This is a pure bash equivalent of cat.

• $1: path as string: the file to print

fs::cat "myFile"

Also see log::printFile if you want to print a file for a user.

fs::cleanTempFiles

Removes all the temporary files and directories that were created by the fs::createTempFile and fs::createTempDirectory functions.

fs::cleanTempFiles

fs::createDirectoryIfNeeded

Create the directory tree if needed.

• $1: path as string: The directory path to create.

Returns:

• ${RETURNED_VALUE}: The absolute path to the directory.

fs::createDirectoryIfNeeded "/my/directory"

fs::createFilePathIfNeeded

Make sure that the given file path exists. Create the directory tree and the file if needed.

• $1: path as string: the file path to create

Returns:

• ${RETURNED_VALUE}: The absolute path of the file.

fs::createFilePathIfNeeded "myFile"

fs::createLink

Create a soft or hard link (original ← link).

Reminder:

• A soft (symbolic) link is a new file that contains a reference to another file or directory in the form of an absolute or relative path.
• A hard link is a directory entry that associates a new pathname with an existing file (inode + data block) on a file system.

See windows::createLink for Windows.

• $1: linked path as string: the path to link to (the original file)
• $2: link path as string: the path where to create the link
• $3: hard link as boolean: (optional) Can be set using the variable _OPTION_HARD_LINK. True to create a hard link, false to create a symbolic link (defaults to false)
• $4: force as boolean: (optional) Can be set using the variable _OPTION_FORCE. True to overwrite the link or file if it already exists. Otherwise, the function will fail on an existing link. (defaults to true)

fs::createLink "/path/to/link" "/path/to/linked"
fs::createLink "/path/to/link" "/path/to/linked" true

The function uses the ln command.

fs::createTempDirectory

Creates a temporary directory.

• ${_OPTION_PATH_ONLY} as bool: (optional) If true, does not create the file, only returns the path. (defaults to false)

Returns:

• ${RETURNED_VALUE}: The created path.

fs::createTempDirectory
local directory="${RETURNED_VALUE}"

Directories created this way are automatically cleaned up by the fs::cleanTempFiles function when valet ends.

fs::createTempFile

Creates a temporary file and return its path.

• ${_OPTION_PATH_ONLY} as bool: (optional) If true, does not create the file, only returns the path. (defaults to false)

Returns:

• ${RETURNED_VALUE}: The created path.

fs::createTempFile
local file="${RETURNED_VALUE}"

Files created this way are automatically cleaned up by the fs::cleanTempFiles function when valet ends.

fs::getCommandPath

Get the absolute path of a command.

• $1: command as string: the command to find

Returns:

• ${RETURNED_VALUE}: The absolute path of the command (or empty if command not found).
• $?:
  • 0 if the command was found
  • 1 otherwise

fs::getCommandPath "command"
echo "${RETURNED_VALUE}"

fs::getFileLineCount

Get the number of lines in a file.

• $1: path as string: the file path to read

Returns:

• ${RETURNED_VALUE}: The number of lines in the file.

fs::getFileLineCount "/path/to/file"
local lineCount="${RETURNED_VALUE}"

TODO: fails to count the last line if empty

fs::getPwdRealPath

Get the real path of the current directory. By default, the ${PWD} variable is the logical path, which may contain symlinks.

fs::getPwdRealPath

Returns:

• ${RETURNED_VALUE}: The realpath for the current directory.

This is a pure bash alternative to realpath or readlink.

fs::getScriptDirectory

This function returns the absolute path of the directory of the script that called it.

Returns:

• ${RETURNED_VALUE}: the directory of the script that called it.

fs::getScriptDirectory
echo "${RETURNED_VALUE}"

fs::head

Print the first lines of a file to stdout. This is a pure bash equivalent of head.

• $1: path as string: The file to print.
• $2: number of lines as int: The number of lines to print.
• $3: to variable as bool: (optional) Can be set using the variable _OPTION_TO_VARIABLE. If true, the output will be stored in the variable RETURNED_ARRAY instead of being printed to stdout. (defaults to false)

fs::head "myFile" 10

#TODO: faster with mapfile + quantum?

fs::isDirectoryWritable

Check if the directory is writable. Creates the directory if it does not exist.

• $1: directory as string: the directory to check
• $2: test file name as string: (optional) Can be set using the variable _OPTION_TEST_FILE_NAME. the name of the file to create in the directory to test the write access

Returns:

• $?:
  • 0 if the directory is writable
  • 1 otherwise

if fs::isDirectoryWritable "/path/to/directory"; then
  echo "The directory is writable."
fi

fs::listDirectories

List all the directories in the given directory.

• $1: directory as string: the directory to list
• $2: recursive as bool: (optional) true to list recursively, false otherwise (defaults to false)
• $3: hidden as bool: (optional) true to list hidden paths, false otherwise (defaults to false)
• $4: directory filter function name as string: (optional) a function name that is called to filter the sub directories (for recursive listing) The function should return 0 if the path is to be kept, 1 otherwise. The function is called with the path as the first argument. (defaults to empty string, no filter)

Returns:

• ${RETURNED_ARRAY[@]}: An array with the list of all the files.

fs::listDirectories "/path/to/directory" true true myFilterFunction
for path in "${RETURNED_ARRAY[@]}"; do
  printf '%s' "${path}"
done

fs::listFiles

List all the files in the given directory.

• $1: directory as string: the directory to list
• $2: recursive as bool: (optional) true to list recursively, false otherwise (defaults to false)
• $3: hidden as bool: (optional) true to list hidden paths, false otherwise (defaults to false)
• $4: directory filter function name as string: (optional) a function name that is called to filter the directories (for recursive listing) The function should return 0 if the path is to be kept, 1 otherwise. The function is called with the path as the first argument. (defaults to empty string, no filter)

Returns:

• ${RETURNED_ARRAY[@]}: An array with the list of all the files.

fs::listFiles "/path/to/directory" true true myFilterFunction
for path in "${RETURNED_ARRAY[@]}"; do
  printf '%s' "${path}"
done

fs::listPaths

List all the paths in the given directory.

• $1: directory as string: the directory to list
• $2: recursive as bool: (optional) true to list recursively, false otherwise (defaults to false)
• $3: hidden as bool: (optional) true to list hidden paths, false otherwise (defaults to false)
• $4: path filter function name as string: (optional) a function name that is called to filter the paths that will be listed The function should return 0 if the path is to be kept, 1 otherwise. The function is called with the path as the first argument. (defaults to empty string, no filter)
• $5: directory filter function name as string: (optional) a function name that is called to filter the directories (for recursive listing) The function should return 0 if the path is to be kept, 1 otherwise. The function is called with the path as the first argument. (defaults to empty string, no filter)

Returns:

• ${RETURNED_ARRAY[@]}: An array with the list of all the paths.

fs::listPaths "/path/to/directory" true true myFilterFunction myFilterDirectoryFunction
for path in "${RETURNED_ARRAY[@]}"; do
  printf '%s' "${path}"
done

• It will correctly list files under symbolic link directories.

fs::readFile

Reads the content of a file and returns it in the global variable RETURNED_VALUE. Uses pure bash.

• $1: path as string: the file path to read
• $2: max char as int: (optional) the maximum number of characters to read (defaults to 0, which means read the whole file)

If the file does not exist, the function will return an empty string instead of failing.

Returns:

• ${RETURNED_VALUE}: The content of the file.

fs::readFile "/path/to/file" && local fileContent="${RETURNED_VALUE}"
fs::readFile "/path/to/file" 500 && local fileContent="${RETURNED_VALUE}"

fs::tail

Print the last lines of a file to stdout. This is a pure bash equivalent of tail. However, because we have to read the whole file, it is not efficient for large files.

• $1: path as string: The file to print.
• $2: number of lines as int: The number of lines to print from the end of the file.
• $3: to variable as bool: (optional) Can be set using the variable _OPTION_TO_VARIABLE. If true, the output will be stored in the variable RETURNED_ARRAY instead of being printed to stdout. (defaults to false)

fs::tail "myFile" 10

#TODO: use mapfile quantum to not have to read the whole file in a single go.

fs::toAbsolutePath

This function returns the absolute path of a path.

If the path exists, it can be resolved to the real path, following symlinks, using the option _OPTION_REALPATH=true.

• $1: path as string: The path to translate to absolute path.
• ${_OPTION_REALPATH} as bool: (optional) true to resolve the path to the real path, following symlinks. (defaults to false)

Returns:

• ${RETURNED_VALUE}: The absolute path of the path.

fs::toAbsolutePath "myPath"
local myPathAbsolutePath="${RETURNED_VALUE}"

This is a pure bash alternative to realpath or readlink. The .. will be processed before following any symlinks, by removing the immediate pathname component.