file_utils.md

Let's create a detailed documentation section for each function and property in the provided Go code. Each section will include an entity name, usage examples, and a reference table detailing parameters, return types, and additional notes.

[FilterFilesByExtension]

Usage

FilterFilesByExtension filters a slice of filenames based on their extensions. It allows you to either include or exclude files based on a list of extensions.

filteredFiles := FilterFilesByExtension(files, []string{"txt", "go"}, true)

Reference

Parameter	Type	Description
files	[]string	The slice of file names to filter.
extensions	[]string	The list of extensions to filter by.
include	bool	Flag indicating whether to include or exclude files with the specified extensions.

Returns	Description
[]string	A slice of filenames filtered based on the extensions.

[ReadFile]

Usage

ReadFile reads the entire content of a file specified by its path and returns the content as a string.

content, err := ReadFile("example.txt")
if err != nil {
    log.Fatal(err)
}
fmt.Println(content)

Reference

Parameter	Type	Description
filePath	string	The path to the file to read.

Returns	Description
string	The content of the file.
error	An error if the read fails, otherwise nil.

[OverwriteFile]

Usage

OverwriteFile overwrites the content of a file at the specified path. If the file does not exist, it is created.

err := OverwriteFile("example.txt", "New content")
if err != nil {
    log.Fatal(err)
}

Reference

Parameter	Type	Description
filePath	string	The path to the file to be overwritten.
content	string	The content to write to the file.

Returns	Description
error	An error if the write fails, otherwise nil.

[FolderExists]

Usage

FolderExists checks if a folder at the specified path exists.

exists := FolderExists("path/to/folder")
fmt.Println(exists) // Outputs: true or false

Reference

Parameter	Type	Description
path	string	The path to the folder to check.

Returns	Description
bool	True if the folder exists, false otherwise.

Certainly! Let's continue with the documentation for the remaining functions.

[GetItemsInFolder]

Usage

GetItemsInFolder retrieves the names of all items (files and directories) in a specified folder.

items, err := GetItemsInFolder("path/to/folder")
if err != nil {
    log.Fatal(err)
}
fmt.Println(items)

Reference

Parameter	Type	Description
folderPath	string	The path to the folder.

Returns	Description
[]string	A slice containing the names of the items in the folder.
error	An error if the operation fails, otherwise nil.

[GetItemsInFolderRecursive]

Usage

GetItemsInFolderRecursive retrieves the names of all items in a specified folder and, if recursive is true, in all its subfolders.

items, err := GetItemsInFolderRecursive("path/to/folder", true)
if err != nil {
    log.Fatal(err)
}
fmt.Println(items)

Reference

Parameter	Type	Description
folderPath	string	The path to the folder.
recursive	bool	Whether to include items in subfolders.

Returns	Description
[]string	A slice containing the names of the items.
error	An error if the operation fails, otherwise nil.

[HasSuffixInArray]

Usage

HasSuffixInArray checks if a given string ends with any of the suffixes in a provided slice and optionally removes the suffix.

result := HasSuffixInArray("filename.txt", []string{"txt", "log"}, true)
fmt.Println(result) // Outputs: "filename" if the suffix was removed

Reference

Parameter	Type	Description
str	string	The string to check.
suffixes	[]string	A slice of suffixes to check against the string.
removeSuffix	bool	Whether to remove the suffix if found.

Returns	Description
string	The modified string if removeSuffix is true, otherwise the original string.

[HasPrefixInArray]

Usage

HasPrefixInArray checks if a given string starts with any of the prefixes in a provided slice and optionally removes the prefix.

result := HasPrefixInArray("example.txt", []string{"ex", "sample"}, true)
fmt.Println(result) // Outputs: "ample.txt" if the prefix was removed

Reference

Parameter	Type	Description
str	string	The string to check.
prefixes	[]string	A slice of prefixes to check against the string.
removePrefix	bool	Whether to remove the prefix if found.

Returns	Description
string	The modified string if removePrefix is true, otherwise the original string.

Absolutely, let's continue and complete the documentation for the remaining functions.

[RemoveDrivePath]

Usage

RemoveDrivePath removes the drive letter from a file path, making it relative if it was absolute.

relativePath := RemoveDrivePath("C:/path/to/file")
fmt.Println(relativePath) // Outputs: "/path/to/file"

Reference

Parameter	Type	Description
folderPath	string	The file path from which to remove the drive letter.

Returns	Description
string	The path without the drive letter.

[IsFileOrFolder]

Usage

IsFileOrFolder determines whether the given path is a file or a directory.

fileType, err := IsFileOrFolder("path/to/item")
if err != nil {
    log.Fatal(err)
}
fmt.Println(fileType) // Outputs: "file" or "dir"

Reference

Parameter	Type	Description
path	string	The path to check.

Returns	Description
string	"file" if the path is a file, "dir" if it's a directory.
error	An error if the operation fails, otherwise nil.

[ConvertPathToOSFormat]

Usage

ConvertPathToOSFormat converts a file path to the OS-specific format.

osPath := ConvertPathToOSFormat("path/to/file")
fmt.Println(osPath) // Outputs: OS-specific path format

Reference

Parameter	Type	Description
inputPath	string	The file path to convert.

Returns	Description
string	The path in OS-specific format.

[JoinAndConvertPathToOSFormat]

Usage

JoinAndConvertPathToOSFormat joins multiple path segments and converts them to the OS-specific format.

path := JoinAndConvertPathToOSFormat("path", "to", "file")
fmt.Println(path) // Outputs: Joined and converted path

Reference

Parameter	Type	Description
inputPathParts	...string	The path segments to join and convert.

Returns	Description
string	The joined and converted path.

[ProcessFilesMatchingPattern]

Usage

ProcessFilesMatchingPattern processes files in a directory that match a specific pattern.

err := ProcessFilesMatchingPattern("path/to/directory", "*.txt", func(filePath string) {
    fmt.Println("Processing file:", filePath)
})
if err != nil {
    log.Fatal(err)
}

Reference

Parameter	Type	Description
directory	string	The directory to search in.
pattern	string	The pattern to match file names against.
predicateFn	func(string)	A function to execute on each matching file.

Returns	Description
error	An error if the operation fails, otherwise nil.

[ProcessFoldersMatchingPattern]

Usage

ProcessFoldersMatchingPattern processes folders in a directory that match a specific pattern.

err := ProcessFoldersMatchingPattern("path/to/directory", "data*", func(folderPath string) {
    fmt.Println("Processing folder:", folderPath)
})
if err != nil {
    log.Fatal(err)
}

Reference

Parameter	Type	Description
directory	string	The directory to search in.
pattern	string	The pattern to match directory names against.
predicateFn	func(string)	A function to execute on each matching directory.

Returns	Description
error	An error if the operation fails, otherwise nil.

[AddContentToFile]

Usage

AddContentToFile adds content to a file at a specified position ("prefix" or "suffix").

err := AddContentToFile("path/to/file.txt", "Content to add", "prefix")
if err != nil {
    log.Fatal(err)
}

Reference

Parameter	Type	Description
filePath	string	The path to the file.
valueToAdd	string	The content to add to the file.
position	string	The position to add the content ("prefix" or "suffix").

Returns	Description
error	An error if the operation fails, otherwise nil.

[AddContentToEachLineInFile]

Usage

AddContentToEachLineInFile adds content to each line of a file using a predicate function that determines the content to add.

err := AddContentToEachLineInFile("path/to/file.txt", func(line string) string {
    return "Prefix " + line
})
if err != nil {
    log.Fatal(err)
}

Reference

Parameter	Type	Description
filePath	string	The path to the file.
predicate	func(string) string	A function that takes a line and returns the new line content.

Returns	Description
error	An error if the operation fails, otherwise nil.

Let's document the additional functions provided.

[RemoveContentFromFile]

Usage

RemoveContentFromFile removes lines from a file that match any string in a provided list.

err := RemoveContentFromFile("path/to/file.txt", []string{"line to remove1", "line to remove2"})
if err != nil {
    log.Fatal(err)
}

Reference

Parameter	Type	Description
filePath	string	The path to the file to modify.
contentToRemove	[]string	A slice of strings to be removed from the file.

Returns	Description
error	An error if the operation fails, otherwise nil.

[MergeDirectories]

Usage

MergeDirectories merges files and directories from a source directory to a target directory, optionally overwriting existing files.

err := MergeDirectories("source/dir", "target/dir", true)
if err != nil {
    log.Fatal(err)
}

Reference

Parameter	Type	Description
sourceDir	string	The source directory path.
targetDir	string	The target directory path.
overwrite	bool	Whether to overwrite existing files in the target directory.

Returns	Description
error	An error if the operation fails, otherwise nil.

[TraverseDirectory]

Usage

TraverseDirectory traverses a directory, applying a predicate function to each item and optionally filtering items with a filter function.

params := TraverseDirectoryParams{
    RootDir: "path/to/dir",
    Predicate: func(path string, info os.FileInfo) {
        fmt.Println("Visiting:", path)
    },
    Filter: func(path string, info os.FileInfo) bool {
        return !info.IsDir() // Return true for files
    },
}
err := TraverseDirectory(params)
if err != nil {
    log.Fatal(err)
}

Reference

Parameter	Type	Description
RootDir	string	The root directory to start traversal.
Predicate	func(string, os.FileInfo)	Function to apply to each item.
Filter	func(string, os.FileInfo) bool	Optional function to filter items during traversal.

Returns	Description
error	An error if the operation fails, otherwise nil.

[DownloadFile]

Usage

DownloadFile downloads a file from a URL and saves it to a local path.

err := DownloadFile("http://example.com/file.txt", "path/to/save/file.txt")
if err != nil {
    log.Fatal(err)
}

Reference

Parameter	Type	Description
url	string	The URL of the file to download.
localPath	string	The local path where the file will be saved.

Returns	Description
error	An error if the operation fails, otherwise nil.

[ExtractArchive]

Usage

ExtractArchive downloads and extracts an archive from a given URL and optionally removes the archive file after extraction.

extractedDir := ExtractArchive("http://example.com/archive.zip", true)
fmt.Println("Extracted directory:", extractedDir)

Reference

Parameter	Type	Description
archiveURL	string	The URL of the archive to download and extract.
removeArchiveFile	bool	Whether to remove the archive file after extraction.

Returns	Description
string	The directory where the archive was extracted.

[GetSourceFilePath]

Usage

GetSourceFilePath retrieves the directory path of the executable.

sourcePath, err := GetSourceFilePath()
if err != nil {
    log.Fatal(err)
}
fmt.Println("Source file path:", sourcePath)

Reference

Returns	Description
string	The directory path of the executable.
error	An error if the operation fails, otherwise nil.

[FindExecutable]

Usage

FindExecutable searches for an executable in a specified directory matching a given prefix.

executablePath := FindExecutable("myApp", "/path/to/search")
fmt.Println("Executable path:", executablePath)

Reference

Parameter	Type	Description
executablePrefix	string	The prefix of the executable to find.
searchDir	string	The directory to search in.

Returns	Description
string	The path to the found executable, or an error message if not found.

[WatchDirectoryParams]

Usage

WatchDirectoryParams is a struct used to configure the parameters for watching a directory for changes.

Reference

Field	Type	Description
DirectoryToWatch	string	The directory to monitor for changes.
DebounceInMs	int	Time in milliseconds to debounce the events.
Predicate	func(event fsnotify.Event)	Function to call when an event occurs.
StartOnWatch	bool	Whether to trigger the predicate function at the start of the watch.
IncludePatterns	[]string	Glob patterns to include in the watch.
ExcludePatterns	[]string	Glob patterns to exclude from the watch.

[WatchDirectory]

Usage

WatchDirectory sets up a watch on a directory, triggering a provided function on file changes, considering inclusion and exclusion patterns.

options := WatchDirectoryParams{
	DirectoryToWatch: "path/to/watch",
	DebounceInMs:     1000,
	Predicate:        func(event fsnotify.Event) { fmt.Println("Change detected:", event.Name) },
	StartOnWatch:     true,
	IncludePatterns:  []string{"*.go"},
	ExcludePatterns:  []string{"*.tmp"},
}
WatchDirectory(options)

[CompileGlobs]

Usage

CompileGlobs compiles a slice of string patterns into glob.Glob objects.

globs := CompileGlobs([]string{"*.txt", "*.go"})

Reference

Parameter	Type	Description
patterns	[]string	The slice of string patterns to compile.

Returns	Description
[]glob.Glob	A slice of compiled glob patterns.

[MatchAnyGlob]

Usage

MatchAnyGlob checks if a given path matches any of the compiled glob patterns.

matches := MatchAnyGlob(globs, "path/to/file.go")
fmt.Println("Matches:", matches)

Reference

Parameter	Type	Description
globs	[]glob.Glob	The compiled glob patterns to match against.
path	string	The path to check against the glob patterns.

Returns	Description
bool	True if the path matches any glob pattern, false otherwise.

[RemovePathPrefix]

Usage

RemovePathPrefix removes a prefix from a path if it matches any in the provided list.

path := RemovePathPrefix("/prefix/path/to/file", []string{"/prefix"})
fmt.Println(path)  // Outputs: "/path/to/file"

Reference

Parameter	Type	Description
path	string	The path to remove the prefix from.
prefixArray	[]string	An array of prefixes to check against the path.

Returns	Description
string	The path with the prefix removed, if a match was found.

[EnsureDirAndCreateFile]

Usage

EnsureDirAndCreateFile ensures that the directory for a file path exists and then creates the file.

file, err := EnsureDirAndCreateFile("/path/to/file.txt")
if err != nil {
	log.Fatal(err)
}
fmt.Println("File created:", file.Name())

Reference

Parameter	Type	Description
filePath	string	The file path where the directory and file will be created.

Returns	Description
*os.File	The file descriptor for the newly created file.
error	An error if the operation fails, otherwise nil.