mirror
/
pkger
mirror of https://github.com/markbates/pkger.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity

docs

This commit is contained in:
Mark Bates 2019-11-11 17:45:39 -05:00
parent c69a63df8d
commit 7067fa6132
2 changed files with 15 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
README.md
View File

@ -2,7 +2,7 @@
[`github.com/markbates/pkger`](https://godoc.org/github.com/markbates/pkger) is a tool for embedding static files into Go binaries. It will, hopefully, be a replacement for [`github.com/gobuffalo/packr/v2`](https://godoc.org/github.com/gobuffalo/packr/v2). [`github.com/markbates/pkger`](https://godoc.org/github.com/markbates/pkger) is a tool for embedding static files into Go binaries. It will, hopefully, be a replacement for [`github.com/gobuffalo/packr/v2`](https://godoc.org/github.com/gobuffalo/packr/v2).
## How it Works ## How it Works (Module Aware Pathing)
Pkger is powered by the dark magic of Go Modules, so they're like, totally required. Pkger is powered by the dark magic of Go Modules, so they're like, totally required.
@ -212,3 +212,17 @@ func run() error {
} }
``` ```
## Understanding the Parser
The [`github.com/markbates/pkger/parser#Parser`](https://godoc.org/github.com/markbates/pkger/parser#Parser) works by statically analyzing the source code of your module using the [`go/parser`](https://godoc.org/go/parser) to find a selection of declarations.
The following declarations in your source code will tell the parser to embed files or folders.
* `pkger.Dir("<path>")` - Embeds all files under the specified path.
* `pkger.Open("<path>")` - Embeds the file, or folder, of the specified path.
* `pkger.Stat("<path>")` - Embeds the file, or folder, of the specified path.
* `pkger.Walk("<path>", filepath.WalkFunc)` - Embeds all files under the specified path.
* `pkger.Include("<path>")` - `Include` is a no-op that directs the pkger tool to include the desired file or folder.

9
pkging/pkger.go
View File

@ -15,15 +15,12 @@ type Pkger interface {
Current() (here.Info, error) Current() (here.Info, error)
// Info returns the here.Info of the here.Path // Info returns the here.Info of the here.Path
// @Parser Directive
Info(p string) (here.Info, error) 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. // 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) 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. // 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 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. // 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.
@ -39,14 +36,8 @@ type Pkger interface {
Walk(p string, wf filepath.WalkFunc) error Walk(p string, wf filepath.WalkFunc) error
// Remove removes the named file or (empty) directory. // Remove removes the named file or (empty) directory.
// @Parser Directive
Remove(name string) error 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). // 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 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
} }