From 1629b861cd8ec927ed79b34536a947dd57ba8b34 Mon Sep 17 00:00:00 2001 From: dudaodong Date: Sun, 30 Jan 2022 15:28:33 +0800 Subject: [PATCH] docs: add doc for package fileutil --- docs/fileutil.md | 444 +++++++++++++++++++++++++++++++++++++++++ docs/fileutil_zh-CN.md | 444 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 888 insertions(+) create mode 100644 docs/fileutil.md create mode 100644 docs/fileutil_zh-CN.md diff --git a/docs/fileutil.md b/docs/fileutil.md new file mode 100644 index 0000000..61a7b4d --- /dev/null +++ b/docs/fileutil.md @@ -0,0 +1,444 @@ +# Fileutil +Package fileutil implements some basic functions for file operations. + +
+ +## Source: + +[https://github.com/duke-git/lancet/blob/main/fileutil/file.go](https://github.com/duke-git/lancet/blob/main/fileutil/file.go) + +
+ +## Usage: +```go +import ( + "github.com/duke-git/lancet/fileutil" +) +``` + +
+ +## Index +- [ClearFile](#ClearFile) +- [CreateFile](#CreateFile) +- [CopyFile](#CopyFile) +- [FileMode](#FileMode) +- [MiMeType](#MiMeType) +- [IsExist](#IsExist) +- [IsLink](#IsLink) +- [IsDir](#IsDir) +- [ListFileNames](#ListFileNames) +- [RemoveFile](#RemoveFile) +- [ReadFileToString](#ReadFileToString) +- [ReadFileByLine](#ReadFileByLine) +- [Zip](#Zip) + +- [UnZip](#UnZip) + +
+ +## Documentation + + + +### ClearFile +

Clear the file content, write empty string to the file.

+ +Signature: + +```go +func ClearFile(path string) error +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + err := fileutil.ClearFile("./test.txt") + if err != nil { + fmt.Println(err) + } +} +``` + +### CreateFile +

Create file in path. return true if create succeed.

+ +Signature: + +```go +func CreateFile(path string) bool +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + isCreatedSucceed := fileutil.CreateFile("./test.txt") + fmt.Println(isCreatedSucceed) +} +``` + + +### CopyFile +

Copy src file to dest file. If dest file exist will overwrite it.

+ +Signature: + +```go +func CopyFile(srcFilePath string, dstFilePath string) error +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + err := fileutil.CopyFile("./test.txt", "./test_copy.txt") + if err != nil { + fmt.Println(err) + } +} +``` + + + +### FileMode +

Return file mode infomation.

+ +Signature: + +```go +func FileMode(path string) (fs.FileMode, error) +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + mode, err := fileutil.FileMode("./test.txt") + if err != nil { + fmt.Println(err) + } + fmt.Println(mode) +} +``` + + + +### MiMeType +

Get file mime type, 'file' param's type should be string or *os.File.

+ +Signature: + +```go +func MiMeType(file interface{}) string +``` +Example: + +```go +package main + +import ( + "fmt" + "os" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + type1 := fileutil.MiMeType("./test.txt") + fmt.Println(type1) //text/plain; charset=utf-8 + + f, _ := os.Open("./file.go") + type2 := fileutil.MiMeType(f) + fmt.Println(type2) //text/plain; charset=utf-8 +} +``` + + + + +### IsExist +

Checks if a file or directory exists.

+ +Signature: + +```go +func IsExist(path string) bool +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + fileutil.CreateFile("./test.txt") + isFileExist := fileutil.IsExist("./test.txt") + fmt.Println(isFileExist) //true +} +``` + + + +### IsLink +

Checks if a file is symbol link or not.

+ +Signature: + +```go +func IsLink(path string) bool +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + isLinkFile := fileutil.IsLink("./test.txt") + fmt.Println(isLinkFile) //false +} +``` + + + +### IsDir +

Checks if the path is directy or not.

+ +Signature: + +```go +func IsDir(path string) bool +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + isDir := fileutil.IsDir("./") + fmt.Println(isDir) //true + + isDir = fileutil.IsDir("./test.txt") + fmt.Println(isDir) //false +} +``` + + + +### ListFileNames +

List all file names in given path.

+ +Signature: + +```go +func ListFileNames(path string) ([]string, error) +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + fileNames, _ := fileutil.ListFileNames("./") + fmt.Println(fileNames) +} +``` + + + +### RemoveFile +

Remove the file of path.

+ +Signature: + +```go +func RemoveFile(path string) error +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + err := fileutil.RemoveFile("./test.txt") + if err != nil { + fmt.Println(err) + } +} +``` + + +### ReadFileToString +

Return string of file content.

+ +Signature: + +```go +func ReadFileToString(path string) (string, error) +``` +Example: + +```go +package main + +import ( + "fmt" + "os" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + path := "./test.txt" + fileutil.CreateFile(path) + + f, _ := os.OpenFile(path, os.O_WRONLY|os.O_TRUNC, 0777) + f.WriteString("hello world") + + content, _ := fileutil.ReadFileToString(path) + fmt.Println(content) //hello world +} +``` + + + +### ReadFileByLine +

Read file line by line, and return slice of lines

+ +Signature: + +```go +func ReadFileByLine(path string)([]string, error) +``` +Example: + +```go +package main + +import ( + "fmt" + "os" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + path := "./text.txt" + fileutil.CreateFile(path) + + f, _ := os.OpenFile(path, os.O_WRONLY|os.O_TRUNC, 0777) + defer f.Close() + f.WriteString("hello\nworld") + + contents, _ := fileutil.ReadFileByLine(path) + fmt.Println(contents) //[]string{"hello", "world"} +} +``` + + + +### Zip +

Create a zip file of fpath, fpath could be a file or a directory.

+ +Signature: + +```go +func Zip(fpath string, destPath string) error +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + err := fileutil.Zip("./test.txt", "./test.zip") + if err != nil { + fmt.Println(err) + } +} +``` + + + + +### UnZip +

Unzip the file and save it to dest path.

+ +Signature: + +```go +func UnZip(zipFile string, destPath string) error +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + err := fileutil.Zip("./test.zip", "./unzip/test.txt") + if err != nil { + fmt.Println(err) + } +} +``` + + + + + diff --git a/docs/fileutil_zh-CN.md b/docs/fileutil_zh-CN.md new file mode 100644 index 0000000..d25ce56 --- /dev/null +++ b/docs/fileutil_zh-CN.md @@ -0,0 +1,444 @@ +# Fileutil +fileutil包支持文件基本操作。 + +
+ +## 源码: + +[https://github.com/duke-git/lancet/blob/main/fileutil/file.go](https://github.com/duke-git/lancet/blob/main/fileutil/file.go) + +
+ +## 用法: +```go +import ( + "github.com/duke-git/lancet/fileutil" +) +``` + +
+ +## 目录 +- [ClearFile](#ClearFile) +- [CreateFile](#CreateFile) +- [CopyFile](#CopyFile) +- [FileMode](#FileMode) +- [MiMeType](#MiMeType) +- [IsExist](#IsExist) +- [IsLink](#IsLink) +- [IsDir](#IsDir) + +- [ListFileNames](#ListFileNames) +- [RemoveFile](#RemoveFile) +- [ReadFileToString](#ReadFileToString) +- [ReadFileByLine](#ReadFileByLine) +- [Zip](#Zip) +- [UnZip](#UnZip) + +
+ +## 文档 + + + +### ClearFile +

清空文件内容

+ +函数签名: + +```go +func ClearFile(path string) error +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + err := fileutil.ClearFile("./test.txt") + if err != nil { + fmt.Println(err) + } +} +``` + +### CreateFile +

创建文件，创建成功返回true, 否则返回false

+ +函数签名: + +```go +func CreateFile(path string) bool +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + isCreatedSucceed := fileutil.CreateFile("./test.txt") + fmt.Println(isCreatedSucceed) +} +``` + + +### CopyFile +

拷贝文件，会覆盖原有的拷贝文件

+ +函数签名: + +```go +func CopyFile(srcFilePath string, dstFilePath string) error +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + err := fileutil.CopyFile("./test.txt", "./test_copy.txt") + if err != nil { + fmt.Println(err) + } +} +``` + + + +### FileMode +

获取文件mode信息

+ +函数签名: + +```go +func FileMode(path string) (fs.FileMode, error) +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + mode, err := fileutil.FileMode("./test.txt") + if err != nil { + fmt.Println(err) + } + fmt.Println(mode) +} +``` + + + +### MiMeType +

获取文件mime类型, 'file'参数的类型必须是string或者*os.File

+ +函数签名: + +```go +func MiMeType(file interface{}) string +``` +例子: + +```go +package main + +import ( + "fmt" + "os" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + type1 := fileutil.MiMeType("./test.txt") + fmt.Println(type1) //text/plain; charset=utf-8 + + f, _ := os.Open("./file.go") + type2 := fileutil.MiMeType(f) + fmt.Println(type2) //text/plain; charset=utf-8 +} +``` + + + + +### IsExist +

判断文件或目录是否存在

+ +函数签名: + +```go +func IsExist(path string) bool +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + fileutil.CreateFile("./test.txt") + isFileExist := fileutil.IsExist("./test.txt") + fmt.Println(isFileExist) //true +} +``` + + + +### IsLink +

判断文件是否是符号链接

+ +函数签名: + +```go +func IsLink(path string) bool +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + isLinkFile := fileutil.IsLink("./test.txt") + fmt.Println(isLinkFile) //false +} +``` + + + +### IsDir +

判断目录是否存在

+ +函数签名: + +```go +func IsDir(path string) bool +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + isDir := fileutil.IsDir("./") + fmt.Println(isDir) //true + + isDir = fileutil.IsDir("./test.txt") + fmt.Println(isDir) //false +} +``` + + + +### ListFileNames +

返回目录下所有文件名

+ +函数签名: + +```go +func ListFileNames(path string) ([]string, error) +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + fileNames, _ := fileutil.ListFileNames("./") + fmt.Println(fileNames) +} +``` + + + +### RemoveFile +

删除文件

+ +函数签名: + +```go +func RemoveFile(path string) error +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + err := fileutil.RemoveFile("./test.txt") + if err != nil { + fmt.Println(err) + } +} +``` + + +### ReadFileToString +

读取文件内容并返回字符串

+ +函数签名: + +```go +func ReadFileToString(path string) (string, error) +``` +例子: + +```go +package main + +import ( + "fmt" + "os" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + path := "./test.txt" + fileutil.CreateFile(path) + + f, _ := os.OpenFile(path, os.O_WRONLY|os.O_TRUNC, 0777) + f.WriteString("hello world") + + content, _ := fileutil.ReadFileToString(path) + fmt.Println(content) //hello world +} +``` + + + +### ReadFileByLine +

按行读取文件内容，返回字符串切片包含每一行

+ +函数签名: + +```go +func ReadFileByLine(path string)([]string, error) +``` +例子: + +```go +package main + +import ( + "fmt" + "os" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + path := "./text.txt" + fileutil.CreateFile(path) + + f, _ := os.OpenFile(path, os.O_WRONLY|os.O_TRUNC, 0777) + defer f.Close() + f.WriteString("hello\nworld") + + contents, _ := fileutil.ReadFileByLine(path) + fmt.Println(contents) //[]string{"hello", "world"} +} +``` + + + +### Zip +

zip压缩文件, fpath参数可以是文件或目录

+ +函数签名: + +```go +func Zip(fpath string, destPath string) error +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + err := fileutil.Zip("./test.txt", "./test.zip") + if err != nil { + fmt.Println(err) + } +} +``` + + + + +### UnZip +

zip解压缩文件并保存在目录中

+ +Signature: + +```go +func UnZip(zipFile string, destPath string) error +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/fileutil" +) + +func main() { + err := fileutil.Zip("./test.zip", "./unzip/test.txt") + if err != nil { + fmt.Println(err) + } +} +``` + + + + +