docs: add doc for package fileutil

docs/fileutil.md

@@ -0,0 +1,444 @@
+# Fileutil
+Package fileutil implements some basic functions for file operations.
+
+<div STYLE="page-break-after: always;"></div>
+
+## Source:
+
+[https://github.com/duke-git/lancet/blob/main/fileutil/file.go](https://github.com/duke-git/lancet/blob/main/fileutil/file.go)
+
+<div STYLE="page-break-after: always;"></div>
+
+## Usage:
+```go
+import (
+    "github.com/duke-git/lancet/fileutil"
+)
+```
+
+<div STYLE="page-break-after: always;"></div>
+
+## 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)
+
+<div STYLE="page-break-after: always;"></div>
+
+## Documentation
+
+
+
+### <span id="ClearFile">ClearFile</span>
+<p>Clear the file content, write empty string to the file.</p>
+
+<b>Signature:</b>
+
+```go
+func ClearFile(path string) error
+```
+<b>Example:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/fileutil"
+)
+
+func main() {
+    err := fileutil.ClearFile("./test.txt")
+    if err != nil {
+        fmt.Println(err)
+    }
+}
+```
+
+### <span id="CreateFile">CreateFile</span>
+<p>Create file in path. return true if create succeed.</p>
+
+<b>Signature:</b>
+
+```go
+func CreateFile(path string) bool
+```
+<b>Example:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/fileutil"
+)
+
+func main() {
+    isCreatedSucceed := fileutil.CreateFile("./test.txt")
+    fmt.Println(isCreatedSucceed)
+}
+```
+
+
+### <span id="CopyFile">CopyFile</span>
+<p>Copy src file to dest file. If dest file exist will overwrite it.</p>
+
+<b>Signature:</b>
+
+```go
+func CopyFile(srcFilePath string, dstFilePath string) error
+```
+<b>Example:</b>
+
+```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)
+	}
+}
+```
+
+
+
+### <span id="FileMode">FileMode</span>
+<p>Return file mode infomation.</p>
+
+<b>Signature:</b>
+
+```go
+func FileMode(path string) (fs.FileMode, error)
+```
+<b>Example:</b>
+
+```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)
+}
+```
+
+
+
+### <span id="MiMeType">MiMeType</span>
+<p>Get file mime type, 'file' param's type should be string or *os.File.</p>
+
+<b>Signature:</b>
+
+```go
+func MiMeType(file interface{}) string
+```
+<b>Example:</b>
+
+```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
+}
+```
+
+
+
+
+### <span id="IsExist">IsExist</span>
+<p>Checks if a file or directory exists.</p>
+
+<b>Signature:</b>
+
+```go
+func IsExist(path string) bool
+```
+<b>Example:</b>
+
+```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
+}
+```
+
+
+
+### <span id="IsLink">IsLink</span>
+<p>Checks if a file is symbol link or not.</p>
+
+<b>Signature:</b>
+
+```go
+func IsLink(path string) bool
+```
+<b>Example:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/fileutil"
+)
+
+func main() {
+    isLinkFile := fileutil.IsLink("./test.txt")
+    fmt.Println(isLinkFile) //false
+}
+```
+
+
+
+### <span id="IsDir">IsDir</span>
+<p>Checks if the path is directy or not.</p>
+
+<b>Signature:</b>
+
+```go
+func IsDir(path string) bool 
+```
+<b>Example:</b>
+
+```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
+}
+```
+
+
+
+### <span id="ListFileNames">ListFileNames</span>
+<p>List all file names in given path.</p>
+
+<b>Signature:</b>
+
+```go
+func ListFileNames(path string) ([]string, error)
+```
+<b>Example:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/fileutil"
+)
+
+func main() {
+    fileNames, _ := fileutil.ListFileNames("./")
+    fmt.Println(fileNames)
+}
+```
+
+
+
+### <span id="RemoveFile">RemoveFile</span>
+<p>Remove the file of path.</p>
+
+<b>Signature:</b>
+
+```go
+func RemoveFile(path string) error
+```
+<b>Example:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/fileutil"
+)
+
+func main() {
+    err := fileutil.RemoveFile("./test.txt")
+    if err != nil {
+		fmt.Println(err)
+	}
+}
+```
+
+
+### <span id="ReadFileToString">ReadFileToString</span>
+<p>Return string of file content.</p>
+
+<b>Signature:</b>
+
+```go
+func ReadFileToString(path string) (string, error)
+```
+<b>Example:</b>
+
+```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
+}
+```
+
+
+
+### <span id="ReadFileByLine">ReadFileByLine</span>
+<p>Read file line by line, and return slice of lines</p>
+
+<b>Signature:</b>
+
+```go
+func ReadFileByLine(path string)([]string, error)
+```
+<b>Example:</b>
+
+```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"}
+}
+```
+
+
+
+### <span id="Zip">Zip</span>
+<p>Create a zip file of fpath, fpath could be a file or a directory.</p>
+
+<b>Signature:</b>
+
+```go
+func Zip(fpath string, destPath string) error
+```
+<b>Example:</b>
+
+```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)
+    }
+}
+```
+
+
+
+
+### <span id="UnZip">UnZip</span>
+<p>Unzip the file and save it to dest path.</p>
+
+<b>Signature:</b>
+
+```go
+func UnZip(zipFile string, destPath string) error
+```
+<b>Example:</b>
+
+```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)
+    }
+}
+```
+
+
+
+
+

docs/fileutil_zh-CN.md

@@ -0,0 +1,444 @@
+# Fileutil
+fileutil包支持文件基本操作。
+
+<div STYLE="page-break-after: always;"></div>
+
+## 源码:
+
+[https://github.com/duke-git/lancet/blob/main/fileutil/file.go](https://github.com/duke-git/lancet/blob/main/fileutil/file.go)
+
+<div STYLE="page-break-after: always;"></div>
+
+## 用法:
+```go
+import (
+    "github.com/duke-git/lancet/fileutil"
+)
+```
+
+<div STYLE="page-break-after: always;"></div>
+
+## 目录
+- [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)
+
+<div STYLE="page-break-after: always;"></div>
+
+## 文档
+
+
+
+### <span id="ClearFile">ClearFile</span>
+<p>清空文件内容</p>
+
+<b>函数签名:</b>
+
+```go
+func ClearFile(path string) error
+```
+<b>例子:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/fileutil"
+)
+
+func main() {
+    err := fileutil.ClearFile("./test.txt")
+    if err != nil {
+        fmt.Println(err)
+    }
+}
+```
+
+### <span id="CreateFile">CreateFile</span>
+<p>创建文件，创建成功返回true, 否则返回false</p>
+
+<b>函数签名:</b>
+
+```go
+func CreateFile(path string) bool
+```
+<b>例子:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/fileutil"
+)
+
+func main() {
+    isCreatedSucceed := fileutil.CreateFile("./test.txt")
+    fmt.Println(isCreatedSucceed)
+}
+```
+
+
+### <span id="CopyFile">CopyFile</span>
+<p>拷贝文件，会覆盖原有的拷贝文件</p>
+
+<b>函数签名:</b>
+
+```go
+func CopyFile(srcFilePath string, dstFilePath string) error
+```
+<b>例子:</b>
+
+```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)
+	}
+}
+```
+
+
+
+### <span id="FileMode">FileMode</span>
+<p>获取文件mode信息</p>
+
+<b>函数签名:</b>
+
+```go
+func FileMode(path string) (fs.FileMode, error)
+```
+<b>例子:</b>
+
+```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)
+}
+```
+
+
+
+### <span id="MiMeType">MiMeType</span>
+<p>获取文件mime类型, 'file'参数的类型必须是string或者*os.File</p>
+
+<b>函数签名:</b>
+
+```go
+func MiMeType(file interface{}) string
+```
+<b>例子:</b>
+
+```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
+}
+```
+
+
+
+
+### <span id="IsExist">IsExist</span>
+<p>判断文件或目录是否存在</p>
+
+<b>函数签名:</b>
+
+```go
+func IsExist(path string) bool
+```
+<b>例子:</b>
+
+```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
+}
+```
+
+
+
+### <span id="IsLink">IsLink</span>
+<p>判断文件是否是符号链接</p>
+
+<b>函数签名:</b>
+
+```go
+func IsLink(path string) bool
+```
+<b>例子:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/fileutil"
+)
+
+func main() {
+    isLinkFile := fileutil.IsLink("./test.txt")
+    fmt.Println(isLinkFile) //false
+}
+```
+
+
+
+### <span id="IsDir">IsDir</span>
+<p>判断目录是否存在</p>
+
+<b>函数签名:</b>
+
+```go
+func IsDir(path string) bool 
+```
+<b>例子:</b>
+
+```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
+}
+```
+
+
+
+### <span id="ListFileNames">ListFileNames</span>
+<p>返回目录下所有文件名</p>
+
+<b>函数签名:</b>
+
+```go
+func ListFileNames(path string) ([]string, error)
+```
+<b>例子:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/fileutil"
+)
+
+func main() {
+    fileNames, _ := fileutil.ListFileNames("./")
+    fmt.Println(fileNames)
+}
+```
+
+
+
+### <span id="RemoveFile">RemoveFile</span>
+<p>删除文件</p>
+
+<b>函数签名:</b>
+
+```go
+func RemoveFile(path string) error
+```
+<b>例子:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/fileutil"
+)
+
+func main() {
+    err := fileutil.RemoveFile("./test.txt")
+    if err != nil {
+		fmt.Println(err)
+	}
+}
+```
+
+
+### <span id="ReadFileToString">ReadFileToString</span>
+<p>读取文件内容并返回字符串</p>
+
+<b>函数签名:</b>
+
+```go
+func ReadFileToString(path string) (string, error)
+```
+<b>例子:</b>
+
+```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
+}
+```
+
+
+
+### <span id="ReadFileByLine">ReadFileByLine</span>
+<p>按行读取文件内容，返回字符串切片包含每一行</p>
+
+<b>函数签名:</b>
+
+```go
+func ReadFileByLine(path string)([]string, error)
+```
+<b>例子:</b>
+
+```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"}
+}
+```
+
+
+
+### <span id="Zip">Zip</span>
+<p>zip压缩文件, fpath参数可以是文件或目录</p>
+
+<b>函数签名:</b>
+
+```go
+func Zip(fpath string, destPath string) error
+```
+<b>例子:</b>
+
+```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)
+    }
+}
+```
+
+
+
+
+### <span id="UnZip">UnZip</span>
+<p>zip解压缩文件并保存在目录中</p>
+
+<b>Signature:</b>
+
+```go
+func UnZip(zipFile string, destPath string) error
+```
+<b>例子:</b>
+
+```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)
+    }
+}
+```
+
+
+
+
+