From e29bc0f03133b1d3d108afe6277d0d224906b9ab Mon Sep 17 00:00:00 2001 From: vitalii Date: Sun, 21 Oct 2018 21:49:28 +0300 Subject: [PATCH] main readme file was updated --- README.md | 565 ++++++++++++------------------------------------------ 1 file changed, 118 insertions(+), 447 deletions(-) diff --git a/README.md b/README.md index 9283c76..9f1cced 100644 --- a/README.md +++ b/README.md @@ -4,470 +4,141 @@ [![GoDoc](https://godoc.org/github.com/studio-b12/gowebdav?status.svg)](https://godoc.org/github.com/studio-b12/gowebdav) [![Go Report Card](https://goreportcard.com/badge/github.com/studio-b12/gowebdav)](https://goreportcard.com/report/github.com/studio-b12/gowebdav) -A golang WebDAV client library and command line tool. +A golang WebDAV client library. -## Install command line tool - -```sh -go get -u github.com/studio-b12/gowebdav/cmd/gowebdav -``` +## Main features +`gowebdav` library allows to perform following actions on the remote WebDAV server: +* [create path](#create-path-on-a-webdav-server) +* [get files list](#get-files-list) +* [download file](#download-file-to-byte-array) +* [upload file](#upload-file-from-byte-array) +* [get information about specified file/folder](#get-information-about-specified-filefolder) +* [move file to another location](#move-file-to-another-location) +* [copy file to another location](#copy-file-to-another-location) +* [delete file](#delete-file) ## Usage -```sh -$ gowebdav --help -Usage of gowebdav - -X string - Method: - LS - STAT +First of all you should create `Client` instance using `NewClient()` function: - MKDIR - MKDIRALL +```go +root := "https://webdav.mydomain.me" +user := "user" +password := "password" - GET [] - PUT [] - - MV - CP - - DEL - - -netrc-file string - read login from netrc file (default "~/.netrc") - -pw string - Password [ENV.PASSWORD] - -root string - WebDAV Endpoint [ENV.ROOT] - -user string - User [ENV.USER] (default "$USER") +c := gowebdav.NewClient(root, user, password) ``` -*gowebdav wrapper script* +After you can use this `Client` to perform actions, described below. -Create a wrapper script for example `$EDITOR ./dav && chmod a+x ./dav` for your -server and use [pass](https://www.passwordstore.org/ "the standard unix password manager") -or similar tools to retrieve the password. +**NOTICE:** we will not check errors in examples, to focus you on the `gowebdav` library's code, but you should do it in your code! -```sh -#!/bin/sh - -ROOT="https://my.dav.server/" \ -USER="foo" \ -PASSWORD="$(pass dav/foo@my.dav.server)" \ -gowebdav $@ +### Create path on a WebDAV server +```go +err := c.Mkdir("folder", 0644) +``` +In case you want to create several folders you can use `c.MkdirAll()`: +```go +err := c.MkdirAll("folder/subfolder/subfolder2", 0644) ``` -*Examples* - -Using the `dav` wrapper: - -```sh -$ ./dav -X LS / - -$ echo hi dav! > hello && ./dav -X PUT /hello - -$ ./dav -X STAT /hello - -$ ./dav -X PUT /hello_dav hello - -$ ./dav -X GET /hello_dav - -$ ./dav -X GET /hello_dav hello.txt +### Get files list +```go +files, _ := c.ReadDir("folder/subfolder") +for _, file := range files { + //notice that [file] has os.FileInfo type + fmt.Println(file.Name()) +} ``` -## LINKS +### Download file to byte array +```go +webdavFilePath := "folder/subfolder/file.txt" +localFilePath := "/tmp/webdav/file.txt" + +bytes, _ := c.Read(webdavFilePath) +ioutil.WriteFile(localFilePath, bytes, 0644) +``` + +### Download file via reader +Also you can use `c.ReadStream()` method: +```go +webdavFilePath := "folder/subfolder/file.txt" +localFilePath := "/tmp/webdav/file.txt" + +reader, _ := c.ReadStream(webdavFilePath) + +file, _ := os.Create(localFilePath) +defer file.Close() + +io.Copy(file, reader) +``` + +### Upload file from byte array +```go +webdavFilePath := "folder/subfolder/file.txt" +localFilePath := "/tmp/webdav/file.txt" + +bytes, _ := ioutil.ReadFile(localFilePath) + +c.Write(webdavFilePath, bytes, 0644) +``` + +### Upload file via writer +```go +webdavFilePath := "folder/subfolder/file.txt" +localFilePath := "/tmp/webdav/file.txt" + +file, _ := os.Open(localFilePath) +defer file.Close() + +c.WriteStream(webdavFilePath, file, 0644) +``` + +### Get information about specified file/folder +```go +webdavFilePath := "folder/subfolder/file.txt" + +info := c.Stat(webdavFilePath) +//notice that [info] has os.FileInfo type +fmt.Println(info) +``` + +### Move file to another location +```go +oldPath := "folder/subfolder/file.txt" +newPath := "folder/subfolder/moved.txt" +isOverwrite := true + +c.Rename(oldPath, newPath, isOverwrite) +``` + +### Copy file to another location +```go +oldPath := "folder/subfolder/file.txt" +newPath := "folder/subfolder/file-copy.txt" +isOverwrite := true + +c.Copy(oldPath, newPath, isOverwrite) +``` + +### Delete file +```go +webdavFilePath := "folder/subfolder/file.txt" + +c.Remove(webdavFilePath) +``` + +## Links + +More details about WebDAV server you can read from following resources: * [RFC 2518 - HTTP Extensions for Distributed Authoring -- WEBDAV](http://www.faqs.org/rfcs/rfc2518.html "RFC 2518 - HTTP Extensions for Distributed Authoring -- WEBDAV") * [RFC 2616 - HTTP/1.1 Status Code Definitions](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html "HTTP/1.1 Status Code Definitions") * [WebDav: Next Generation Collaborative Web Authoring By Lisa Dusseaul](https://books.google.de/books?isbn=0130652083 "WebDav: Next Generation Collaborative Web Authoring By Lisa Dusseault") -## API +## Contributing +All contributing are welcome. If you have any suggestions or find some bug - please create an Issue to let us make this project better. We appreciate your help! -`import "github.com/studio-b12/gowebdav"` - -* [Overview](#pkg-overview) -* [Index](#pkg-index) -* [Examples](#pkg-examples) -* [Subdirectories](#pkg-subdirectories) - -### Overview -Package gowebdav is a WebDAV client library with a command line tool -included. - -### Index -* [func FixSlash(s string) string](#FixSlash) -* [func FixSlashes(s string) string](#FixSlashes) -* [func Join(path0 string, path1 string) string](#Join) -* [func PathEscape(path string) string](#PathEscape) -* [func ReadConfig(uri, netrc string) (string, string)](#ReadConfig) -* [func String(r io.Reader) string](#String) -* [type Authenticator](#Authenticator) -* [type BasicAuth](#BasicAuth) - * [func (b *BasicAuth) Authorize(c *Client, method string, path string)](#BasicAuth.Authorize) - * [func (b *BasicAuth) Pass() string](#BasicAuth.Pass) - * [func (b *BasicAuth) Type() string](#BasicAuth.Type) - * [func (b *BasicAuth) User() string](#BasicAuth.User) -* [type Client](#Client) - * [func NewClient(uri, user, pw string) *Client](#NewClient) - * [func (c *Client) Connect() error](#Client.Connect) - * [func (c *Client) Copy(oldpath, newpath string, overwrite bool) error](#Client.Copy) - * [func (c *Client) Mkdir(path string, _ os.FileMode) error](#Client.Mkdir) - * [func (c *Client) MkdirAll(path string, _ os.FileMode) error](#Client.MkdirAll) - * [func (c *Client) Read(path string) ([]byte, error)](#Client.Read) - * [func (c *Client) ReadDir(path string) ([]os.FileInfo, error)](#Client.ReadDir) - * [func (c *Client) ReadStream(path string) (io.ReadCloser, error)](#Client.ReadStream) - * [func (c *Client) Remove(path string) error](#Client.Remove) - * [func (c *Client) RemoveAll(path string) error](#Client.RemoveAll) - * [func (c *Client) Rename(oldpath, newpath string, overwrite bool) error](#Client.Rename) - * [func (c *Client) SetHeader(key, value string)](#Client.SetHeader) - * [func (c *Client) SetTimeout(timeout time.Duration)](#Client.SetTimeout) - * [func (c *Client) SetTransport(transport http.RoundTripper)](#Client.SetTransport) - * [func (c *Client) Stat(path string) (os.FileInfo, error)](#Client.Stat) - * [func (c *Client) Write(path string, data []byte, _ os.FileMode) error](#Client.Write) - * [func (c *Client) WriteStream(path string, stream io.Reader, _ os.FileMode) error](#Client.WriteStream) -* [type DigestAuth](#DigestAuth) - * [func (d *DigestAuth) Authorize(c *Client, method string, path string)](#DigestAuth.Authorize) - * [func (d *DigestAuth) Pass() string](#DigestAuth.Pass) - * [func (d *DigestAuth) Type() string](#DigestAuth.Type) - * [func (d *DigestAuth) User() string](#DigestAuth.User) -* [type File](#File) - * [func (f File) ContentType() string](#File.ContentType) - * [func (f File) ETag() string](#File.ETag) - * [func (f File) IsDir() bool](#File.IsDir) - * [func (f File) ModTime() time.Time](#File.ModTime) - * [func (f File) Mode() os.FileMode](#File.Mode) - * [func (f File) Name() string](#File.Name) - * [func (f File) Size() int64](#File.Size) - * [func (f File) String() string](#File.String) - * [func (f File) Sys() interface{}](#File.Sys) -* [type NoAuth](#NoAuth) - * [func (n *NoAuth) Authorize(c *Client, method string, path string)](#NoAuth.Authorize) - * [func (n *NoAuth) Pass() string](#NoAuth.Pass) - * [func (n *NoAuth) Type() string](#NoAuth.Type) - * [func (n *NoAuth) User() string](#NoAuth.User) - -##### Examples -* [PathEscape](#example_PathEscape) - -##### Package files -[basicAuth.go](https://github.com/studio-b12/gowebdav/blob/master/basicAuth.go) [client.go](https://github.com/studio-b12/gowebdav/blob/master/client.go) [digestAuth.go](https://github.com/studio-b12/gowebdav/blob/master/digestAuth.go) [doc.go](https://github.com/studio-b12/gowebdav/blob/master/doc.go) [file.go](https://github.com/studio-b12/gowebdav/blob/master/file.go) [netrc.go](https://github.com/studio-b12/gowebdav/blob/master/netrc.go) [requests.go](https://github.com/studio-b12/gowebdav/blob/master/requests.go) [utils.go](https://github.com/studio-b12/gowebdav/blob/master/utils.go) - -### func [FixSlash](https://github.com/studio-b12/gowebdav/blob/master/utils.go?s=707:737#L45) -``` go -func FixSlash(s string) string -``` -FixSlash appends a trailing / to our string - -### func [FixSlashes](https://github.com/studio-b12/gowebdav/blob/master/utils.go?s=859:891#L53) -``` go -func FixSlashes(s string) string -``` -FixSlashes appends and prepends a / if they are missing - -### func [Join](https://github.com/studio-b12/gowebdav/blob/master/utils.go?s=976:1020#L61) -``` go -func Join(path0 string, path1 string) string -``` -Join joins two paths - -### func [PathEscape](https://github.com/studio-b12/gowebdav/blob/master/utils.go?s=506:541#L36) -``` go -func PathEscape(path string) string -``` -PathEscape escapes all segemnts of a given path - -### func [ReadConfig](https://github.com/studio-b12/gowebdav/blob/master/netrc.go?s=428:479#L27) -``` go -func ReadConfig(uri, netrc string) (string, string) -``` -ReadConfig reads login and password configuration from ~/.netrc -machine foo.com login username password 123456 - -### func [String](https://github.com/studio-b12/gowebdav/blob/master/utils.go?s=1150:1181#L66) -``` go -func String(r io.Reader) string -``` -String pulls a string out of our io.Reader - -### type [Authenticator](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=285:398#L24) -``` go -type Authenticator interface { - Type() string - User() string - Pass() string - Authorize(*Client, string, string) -} -``` -Authenticator stub - -### type [BasicAuth](https://github.com/studio-b12/gowebdav/blob/master/basicAuth.go?s=94:145#L8) -``` go -type BasicAuth struct { - // contains filtered or unexported fields -} -``` -BasicAuth structure holds our credentials - -#### func (\*BasicAuth) [Authorize](https://github.com/studio-b12/gowebdav/blob/master/basicAuth.go?s=461:529#L29) -``` go -func (b *BasicAuth) Authorize(c *Client, method string, path string) -``` -Authorize the current request - -#### func (\*BasicAuth) [Pass](https://github.com/studio-b12/gowebdav/blob/master/basicAuth.go?s=376:409#L24) -``` go -func (b *BasicAuth) Pass() string -``` -Pass holds the BasicAuth password - -#### func (\*BasicAuth) [Type](https://github.com/studio-b12/gowebdav/blob/master/basicAuth.go?s=189:222#L14) -``` go -func (b *BasicAuth) Type() string -``` -Type identifies the BasicAuthenticator - -#### func (\*BasicAuth) [User](https://github.com/studio-b12/gowebdav/blob/master/basicAuth.go?s=285:318#L19) -``` go -func (b *BasicAuth) User() string -``` -User holds the BasicAuth username - -### type [Client](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=157:261#L16) -``` go -type Client struct { - // contains filtered or unexported fields -} -``` -Client defines our structure - -#### func [NewClient](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=902:946#L57) -``` go -func NewClient(uri, user, pw string) *Client -``` -NewClient creates a new instance of client - -#### func (\*Client) [Connect](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=1516:1548#L77) -``` go -func (c *Client) Connect() error -``` -Connect connects to our dav server - -#### func (\*Client) [Copy](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=6438:6506#L303) -``` go -func (c *Client) Copy(oldpath, newpath string, overwrite bool) error -``` -Copy copies a file from A to B - -#### func (\*Client) [Mkdir](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=5529:5585#L262) -``` go -func (c *Client) Mkdir(path string, _ os.FileMode) error -``` -Mkdir makes a directory - -#### func (\*Client) [MkdirAll](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=5764:5823#L273) -``` go -func (c *Client) MkdirAll(path string, _ os.FileMode) error -``` -MkdirAll like mkdir -p, but for webdav - -#### func (\*Client) [Read](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=6612:6662#L308) -``` go -func (c *Client) Read(path string) ([]byte, error) -``` -Read reads the contents of a remote file - -#### func (\*Client) [ReadDir](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=2604:2664#L120) -``` go -func (c *Client) ReadDir(path string) ([]os.FileInfo, error) -``` -ReadDir reads the contents of a remote directory - -#### func (\*Client) [ReadStream](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=6973:7036#L326) -``` go -func (c *Client) ReadStream(path string) (io.ReadCloser, error) -``` -ReadStream reads the stream for a given path - -#### func (\*Client) [Remove](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=5035:5077#L239) -``` go -func (c *Client) Remove(path string) error -``` -Remove removes a remote file - -#### func (\*Client) [RemoveAll](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=5143:5188#L244) -``` go -func (c *Client) RemoveAll(path string) error -``` -RemoveAll removes remote files - -#### func (\*Client) [Rename](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=6272:6342#L298) -``` go -func (c *Client) Rename(oldpath, newpath string, overwrite bool) error -``` -Rename moves a file from A to B - -#### func (\*Client) [SetHeader](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=1099:1144#L62) -``` go -func (c *Client) SetHeader(key, value string) -``` -SetHeader lets us set arbitrary headers for a given client - -#### func (\*Client) [SetTimeout](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=1244:1294#L67) -``` go -func (c *Client) SetTimeout(timeout time.Duration) -``` -SetTimeout exposes the ability to set a time limit for requests - -#### func (\*Client) [SetTransport](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=1387:1445#L72) -``` go -func (c *Client) SetTransport(transport http.RoundTripper) -``` -SetTransport exposes the ability to define custom transports - -#### func (\*Client) [Stat](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=3991:4046#L187) -``` go -func (c *Client) Stat(path string) (os.FileInfo, error) -``` -Stat returns the file stats for a specified path - -#### func (\*Client) [Write](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=7327:7396#L341) -``` go -func (c *Client) Write(path string, data []byte, _ os.FileMode) error -``` -Write writes data to a given path - -#### func (\*Client) [WriteStream](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=7752:7832#L364) -``` go -func (c *Client) WriteStream(path string, stream io.Reader, _ os.FileMode) error -``` -WriteStream writes a stream - -### type [DigestAuth](https://github.com/studio-b12/gowebdav/blob/master/digestAuth.go?s=157:254#L14) -``` go -type DigestAuth struct { - // contains filtered or unexported fields -} -``` -DigestAuth structure holds our credentials - -#### func (\*DigestAuth) [Authorize](https://github.com/studio-b12/gowebdav/blob/master/digestAuth.go?s=577:646#L36) -``` go -func (d *DigestAuth) Authorize(c *Client, method string, path string) -``` -Authorize the current request - -#### func (\*DigestAuth) [Pass](https://github.com/studio-b12/gowebdav/blob/master/digestAuth.go?s=491:525#L31) -``` go -func (d *DigestAuth) Pass() string -``` -Pass holds the DigestAuth password - -#### func (\*DigestAuth) [Type](https://github.com/studio-b12/gowebdav/blob/master/digestAuth.go?s=299:333#L21) -``` go -func (d *DigestAuth) Type() string -``` -Type identifies the DigestAuthenticator - -#### func (\*DigestAuth) [User](https://github.com/studio-b12/gowebdav/blob/master/digestAuth.go?s=398:432#L26) -``` go -func (d *DigestAuth) User() string -``` -User holds the DigestAuth username - -### type [File](https://github.com/studio-b12/gowebdav/blob/master/file.go?s=93:253#L10) -``` go -type File struct { - // contains filtered or unexported fields -} -``` -File is our structure for a given file - -#### func (File) [ContentType](https://github.com/studio-b12/gowebdav/blob/master/file.go?s=388:422#L26) -``` go -func (f File) ContentType() string -``` -ContentType returns the content type of a file - -#### func (File) [ETag](https://github.com/studio-b12/gowebdav/blob/master/file.go?s=841:868#L51) -``` go -func (f File) ETag() string -``` -ETag returns the ETag of a file - -#### func (File) [IsDir](https://github.com/studio-b12/gowebdav/blob/master/file.go?s=947:973#L56) -``` go -func (f File) IsDir() bool -``` -IsDir let us see if a given file is a directory or not - -#### func (File) [ModTime](https://github.com/studio-b12/gowebdav/blob/master/file.go?s=748:781#L46) -``` go -func (f File) ModTime() time.Time -``` -ModTime returns the modified time of a file - -#### func (File) [Mode](https://github.com/studio-b12/gowebdav/blob/master/file.go?s=577:609#L36) -``` go -func (f File) Mode() os.FileMode -``` -Mode will return the mode of a given file - -#### func (File) [Name](https://github.com/studio-b12/gowebdav/blob/master/file.go?s=290:317#L21) -``` go -func (f File) Name() string -``` -Name returns the name of a file - -#### func (File) [Size](https://github.com/studio-b12/gowebdav/blob/master/file.go?s=485:511#L31) -``` go -func (f File) Size() int64 -``` -Size returns the size of a file - -#### func (File) [String](https://github.com/studio-b12/gowebdav/blob/master/file.go?s=1095:1124#L66) -``` go -func (f File) String() string -``` -String lets us see file information - -#### func (File) [Sys](https://github.com/studio-b12/gowebdav/blob/master/file.go?s=1007:1038#L61) -``` go -func (f File) Sys() interface{} -``` -Sys ???? - -### type [NoAuth](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=442:490#L32) -``` go -type NoAuth struct { - // contains filtered or unexported fields -} -``` -NoAuth structure holds our credentials - -#### func (\*NoAuth) [Authorize](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=785:850#L53) -``` go -func (n *NoAuth) Authorize(c *Client, method string, path string) -``` -Authorize the current request - -#### func (\*NoAuth) [Pass](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=703:733#L48) -``` go -func (n *NoAuth) Pass() string -``` -Pass returns the current password - -#### func (\*NoAuth) [Type](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=529:559#L38) -``` go -func (n *NoAuth) Type() string -``` -Type identifies the authenticator - -#### func (\*NoAuth) [User](https://github.com/studio-b12/gowebdav/blob/master/client.go?s=615:645#L43) -``` go -func (n *NoAuth) User() string -``` -User returns the current user - -- - - -Generated by [godoc2md](http://godoc.org/github.com/davecheney/godoc2md) +## License +This library is distributed under the BSD 3-Clause license found in the [LICENSE](https://github.com/studio-b12/gowebdav/blob/master/LICENSE) file.