From b3c81b5fd3a94a5aeb66b6108ade3e84c8cc1da1 Mon Sep 17 00:00:00 2001 From: Mark Bates Date: Mon, 11 Nov 2019 17:21:59 -0500 Subject: [PATCH] docs --- README.md | 130 +++++++++++++++++------------------------------- pkging/pkger.go | 12 +++++ 2 files changed, 57 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index 68914d4..27fefd0 100644 --- a/README.md +++ b/README.md @@ -63,11 +63,54 @@ package // Pkger stuff here ``` -## Usage +## Reference Application + +The reference application for the `README` examples, as well as all testing, can be found at [https://github.com/markbates/pkger/tree/master/pkging/pkgtest/testdata/ref](https://github.com/markbates/pkger/tree/master/pkging/pkgtest/testdata/ref). + +``` +├── actions +│   └── actions.go +├── assets +│   ├── css +│   │   ├── _buffalo.scss +│   │   └── application.scss +│   ├── images +│   │   ├── favicon.ico +│   │   └── logo.svg +│   └── js +│   └── application.js +├── go.mod +├── go.sum +├── locales +│   └── all.en-us.yaml +├── main.go +├── mod +│   └── mod.go +├── models +│   └── models.go +├── public +│   ├── assets +│   │   └── app.css +│   ├── images +│   │   └── img1.png +│   ├── index.html +│   └── robots.txt +├── templates +│   ├── _flash.plush.html +│   ├── application.plush.html +│   └── index.plush.html +└── web + └── web.go + +13 directories, 20 files +``` + + +## API Usage Pkger's API is modeled on that of the [`os`](https://godoc.org/os) package in Go's standard library. This makes Pkger usage familiar to Go developers. - +The two most important interfaces are [`github.com/markbates/pkger/pkging#Pkger`](https://godoc.org/github.com/markbates/pkger/pkging#Pkger) and [`github.com/markbates/pkger/pkging#File`](https://godoc.org/github.com/markbates/pkger/pkging#File). ```go type Pkger interface { @@ -97,86 +140,3 @@ type File interface { } ``` -```bash -├── go.mod -├── go.sum -├── main.go -├── public -│   ├── images -│   │   ├── mark-small.png -│   │   ├── img1.png -│   │   ├── mark_250px.png -│   │   └── mark_400px.png -│   └── index.html -``` - -```go -package main - -import ( - "fmt" - "log" - "os" - "text/tabwriter" - "time" - - "github.com/markbates/pkger" -) - -func main() { - if err := run(); err != nil { - log.Fatal(err) - } -} - -func run() error { - w := tabwriter.NewWriter(os.Stdout, 0, 0, 0, ' ', tabwriter.Debug) - defer w.Flush() - - return pkger.Walk("/public", func(path string, info os.FileInfo, err error) error { - if err != nil { - return err - } - - fmt.Fprintf(w, - "%s \t %d \t %s \t %s \t\n", - info.Name(), - info.Size(), - info.Mode(), - info.ModTime().Format(time.RFC3339), - ) - - return nil - }) - -} -``` - -### Output Without Packing - -```bash -# compile the go binary as usual and run the app: -$ go build -v; ./app - -public | 128 | drwxr-xr-x | 2019-10-18T16:24:55-04:00 | -images | 128 | drwxr-xr-x | 2019-10-18T16:24:55-04:00 | -img1.png | 27718 | -rw-r--r-- | 2019-10-18T16:24:55-04:00 | -img2.png | 27718 | -rw-r--r-- | 2019-10-18T16:24:55-04:00 | -index.html | 257 | -rw-r--r-- | 2019-10-18T16:24:55-04:00 | -``` - -### Output With Packing - -```bash -# run the pkger cli to generate a pkged.go file: -$ pkger - -# compile the go binary as usual and run the app: -$ go build -v; ./app - -public | 128 | drwxr-xr-x | 2019-10-18T16:24:55-04:00 | -images | 128 | drwxr-xr-x | 2019-10-18T16:24:55-04:00 | -img1.png | 27718 | -rw-r--r-- | 2019-10-18T16:24:55-04:00 | -img2.png | 27718 | -rw-r--r-- | 2019-10-18T16:24:55-04:00 | -index.html | 257 | -rw-r--r-- | 2019-10-18T16:24:55-04:00 | -``` diff --git a/pkging/pkger.go b/pkging/pkger.go index 0022db2..c510ff8 100644 --- a/pkging/pkger.go +++ b/pkging/pkger.go @@ -15,26 +15,38 @@ type Pkger interface { Current() (here.Info, error) // Info returns the here.Info of the here.Path + // @Parser Directive Info(p string) (here.Info, error) // Create creates the named file with mode 0666 (before umask) - It's actually 0644, truncating it if it already exists. If successful, methods on the returned File can be used for I/O; the associated file descriptor has mode O_RDWR. + // @Parser Directive Create(name string) (File, error) // MkdirAll creates a directory named path, along with any necessary parents, and returns nil, or else returns an error. The permission bits perm (before umask) are used for all directories that MkdirAll creates. If path is already a directory, MkdirAll does nothing and returns nil. + // @Parser Directive MkdirAll(p string, perm os.FileMode) error // Open opens the named file for reading. If successful, methods on the returned file can be used for reading; the associated file descriptor has mode O_RDONLY. + // @Parser Directive Open(name string) (File, error) // Stat returns a FileInfo describing the named file. + // @Parser Directive Stat(name string) (os.FileInfo, error) // Walk walks the file tree rooted at root, calling walkFn for each file or directory in the tree, including root. All errors that arise visiting files and directories are filtered by walkFn. The files are walked in lexical order, which makes the output deterministic but means that for very large directories Walk can be inefficient. Walk does not follow symbolic links. - That is from the standard library. I know. Their grammar teachers can not be happy with them right now. + // @Parser Directive Walk(p string, wf filepath.WalkFunc) error // Remove removes the named file or (empty) directory. + // @Parser Directive Remove(name string) error // RemoveAll removes path and any children it contains. It removes everything it can but returns the first error it encounters. If the path does not exist, RemoveAll returns nil (no error). + // @Parser Directive RemoveAll(path string) error + + // Include is a no-op that directs the pkger tool to include the desired file or folder. + // @Parser Directive + // pkger.Include }