docs

apply.go

@@ -6,7 +6,13 @@ import (
 	"github.com/markbates/pkger/pkging"
 )
 
+// Apply will wrap the current implementation
+// of pkger.Pkger with the new pkg. This allows
+// for layering of pkging.Pkger implementations.
 func Apply(pkg pkging.Pkger, err error) error {
+	if err != nil {
+		return err
+	}
 	gil.Lock()
 	defer gil.Unlock()
 	current = pkging.Wrap(current, pkg)

apply_debug.go

@@ -12,6 +12,9 @@ import (
 func Apply(pkg pkging.Pkger, err error) error {
 	gil.Lock()
 	defer gil.Unlock()
+	if err != nil {
+		return err
+	}
 	if err := pkgutil.Dump(os.Stdout, pkg); err != nil {
 		return err
 	}

doc.go

@@ -1,21 +0,0 @@
-/*
-This package is WIP. Please use/test/try and report issues, but be careful with production. OK?
-
-Pkger is powered by the dark magic of Go Modules, so they're like, totally required.
-
-With Go Modules pkger can resolve packages with accuracy. No more guessing and trying to
-figure out build paths, GOPATHS, etc... for this tired old lad.
-
-With the module's path correctly resolved, it can serve as the "root" directory for that
-module, and all files in that module's directory are available.
-
-		Paths:
-		* Paths should use UNIX style paths:
-			/cmd/pkger/main.go
-		* If unspecified the path's package is assumed to be the current module.
-		* Packages can specified in at the beginning of a path with a `:` seperator.
-			github.com/markbates/pkger:/cmd/pkger/main.go
-
-		"github.com/gobuffalo/buffalo:/go.mod" => $GOPATH/pkg/mod/github.com/gobuffalo/buffalo@v0.14.7/go.mod
-*/
-package pkger

pkger.go

@@ -35,22 +35,27 @@ func impl() pkging.Pkger {
 	return current
 }
 
+// Parse the string in here.Path format.
 func Parse(p string) (here.Path, error) {
 	return impl().Parse(p)
 }
 
+// Abs returns an absolute representation of path. If the path is not absolute it will be joined with the current working directory to turn it into an absolute path. The absolute path name for a given file is not guaranteed to be unique. Abs calls Clean on the result.
 func Abs(p string) (string, error) {
 	return impl().Abs(p)
 }
 
+// AbsPath returns an absolute representation of here.Path. If the path is not absolute it will be joined with the current working directory to turn it into an absolute path. The absolute path name for a given file is not guaranteed to be unique. AbsPath calls Clean on the result.
 func AbsPath(p here.Path) (string, error) {
 	return impl().AbsPath(p)
 }
 
+// Current returns the here.Info representing the current Pkger implementation.
 func Current() (here.Info, error) {
 	return impl().Current()
 }
 
+// Info returns the here.Info of the here.Path
 func Info(p string) (here.Info, error) {
 	return impl().Info(p)
 }

pkging/mem/mem.go

@@ -17,12 +17,7 @@ import (
 
 var _ pkging.Pkger = &Pkger{}
 
-func WithInfo(fx *Pkger, infos ...here.Info) {
+// New returns *Pkger for the provided here.Info
-	for _, info := range infos {
-		fx.infos.Store(info.ImportPath, info)
-	}
-}
-
 func New(info here.Info) (*Pkger, error) {
 	f := &Pkger{
 		infos:   &maps.Infos{},
@@ -46,6 +41,7 @@ type jay struct {
 	Current here.Info        `json:"current"`
 }
 
+// MarshalJSON creates a fully re-hydratable JSON representation of *Pkger
 func (p *Pkger) MarshalJSON() ([]byte, error) {
 	files := map[string]*File{}
 
@@ -65,6 +61,7 @@ func (p *Pkger) MarshalJSON() ([]byte, error) {
 	})
 }
 
+// UnmarshalJSON re-hydrates the *Pkger
 func (p *Pkger) UnmarshalJSON(b []byte) error {
 	y := jay{}
 
@@ -87,6 +84,7 @@ func (p *Pkger) UnmarshalJSON(b []byte) error {
 	return nil
 }
 
+// Abs returns an absolute representation of path. If the path is not absolute it will be joined with the current working directory to turn it into an absolute path. The absolute path name for a given file is not guaranteed to be unique. Abs calls Clean on the result.
 func (f *Pkger) Abs(p string) (string, error) {
 	pt, err := f.Parse(p)
 	if err != nil {
@@ -95,14 +93,17 @@ func (f *Pkger) Abs(p string) (string, error) {
 	return f.AbsPath(pt)
 }
 
+// AbsPath returns an absolute representation of here.Path. If the path is not absolute it will be joined with the current working directory to turn it into an absolute path. The absolute path name for a given file is not guaranteed to be unique. AbsPath calls Clean on the result.
 func (f *Pkger) AbsPath(pt here.Path) (string, error) {
 	return pt.String(), nil
 }
 
+// Current returns the here.Info representing the current Pkger implementation.
 func (f *Pkger) Current() (here.Info, error) {
 	return f.current, nil
 }
 
+// Info returns the here.Info of the here.Path
 func (f *Pkger) Info(p string) (here.Info, error) {
 	info, ok := f.infos.Load(p)
 	if !ok {
@@ -112,10 +113,12 @@ func (f *Pkger) Info(p string) (here.Info, error) {
 	return info, nil
 }
 
+// Parse the string in here.Path format.
 func (f *Pkger) Parse(p string) (here.Path, error) {
 	return f.current.Parse(p)
 }
 
+// Remove removes the named file or (empty) directory.
 func (fx *Pkger) Remove(name string) error {
 	pt, err := fx.Parse(name)
 	if err != nil {
@@ -130,6 +133,7 @@ func (fx *Pkger) Remove(name string) error {
 	return nil
 }
 
+// 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).
 func (fx *Pkger) RemoveAll(name string) error {
 	pt, err := fx.Parse(name)
 	if err != nil {
@@ -146,6 +150,7 @@ func (fx *Pkger) RemoveAll(name string) error {
 	return nil
 }
 
+// Add copies the pkging.File into the *Pkger
 func (fx *Pkger) Add(f pkging.File) error {
 	fx.MkdirAll("/", 0755)
 	info, err := f.Stat()
@@ -180,6 +185,7 @@ func (fx *Pkger) Add(f pkging.File) error {
 	return nil
 }
 
+// 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.
 func (fx *Pkger) Create(name string) (pkging.File, error) {
 	fx.MkdirAll("/", 0755)
 	pt, err := fx.Parse(name)
@@ -215,6 +221,7 @@ func (fx *Pkger) Create(name string) (pkging.File, error) {
 	return f, 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.
 func (fx *Pkger) MkdirAll(p string, perm os.FileMode) error {
 	path, err := fx.Parse(p)
 	if err != nil {
@@ -267,6 +274,7 @@ func (fx *Pkger) 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.
 func (fx *Pkger) Open(name string) (pkging.File, error) {
 	pt, err := fx.Parse(name)
 	if err != nil {
@@ -296,6 +304,7 @@ func (fx *Pkger) Open(name string) (pkging.File, error) {
 	return nf, nil
 }
 
+// Stat returns a FileInfo describing the named file.
 func (fx *Pkger) Stat(name string) (os.FileInfo, error) {
 	pt, err := fx.Parse(name)
 	if err != nil {
@@ -308,6 +317,7 @@ func (fx *Pkger) Stat(name string) (os.FileInfo, error) {
 	return nil, fmt.Errorf("could not stat %s", pt)
 }
 
+// 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.
 func (f *Pkger) Walk(p string, wf filepath.WalkFunc) error {
 	keys := f.files.Keys()
 

pkging/mem/stuffing.go

@@ -30,7 +30,6 @@ func Stuff(w io.Writer, cur here.Info, paths []here.Path) error {
 			}
 
 			return nil
-			// WithInfo(ng, og)
 		}()
 		if err != nil {
 			return err

pkging/pkger.go

@@ -8,11 +8,19 @@ import (
 )
 
 type Pkger interface {
+	// Parse the string in here.Path format.
 	Parse(p string) (here.Path, error)
+
+	// Abs returns an absolute representation of path. If the path is not absolute it will be joined with the current working directory to turn it into an absolute path. The absolute path name for a given file is not guaranteed to be unique. Abs calls Clean on the result.
 	Abs(p string) (string, error)
+
+	// AbsPath returns an absolute representation of here.Path. If the path is not absolute it will be joined with the current working directory to turn it into an absolute path. The absolute path name for a given file is not guaranteed to be unique. AbsPath calls Clean on the result.
 	AbsPath(here.Path) (string, error)
 
+	// Current returns the here.Info representing the current Pkger implementation.
 	Current() (here.Info, error)
+
+	// Info returns the here.Info of the here.Path
 	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.

pkging/stdos/stdos.go

@@ -18,6 +18,7 @@ type Pkger struct {
 	infos *maps.Infos
 }
 
+// Abs returns an absolute representation of path. If the path is not absolute it will be joined with the current working directory to turn it into an absolute path. The absolute path name for a given file is not guaranteed to be unique. Abs calls Clean on the result.
 func (f *Pkger) Abs(p string) (string, error) {
 	pt, err := f.Parse(p)
 	if err != nil {
@@ -26,6 +27,7 @@ func (f *Pkger) Abs(p string) (string, error) {
 	return f.AbsPath(pt)
 }
 
+// AbsPath returns an absolute representation of here.Path. If the path is not absolute it will be joined with the current working directory to turn it into an absolute path. The absolute path name for a given file is not guaranteed to be unique. AbsPath calls Clean on the result.
 func (f *Pkger) AbsPath(pt here.Path) (string, error) {
 	if pt.Pkg == f.Here.ImportPath {
 		return filepath.Join(f.Here.Dir, pt.Name), nil
@@ -37,6 +39,7 @@ func (f *Pkger) AbsPath(pt here.Path) (string, error) {
 	return filepath.Join(info.Dir, pt.Name), nil
 }
 
+// New returns *Pkger for the provided here.Info
 func New(her here.Info) (*Pkger, error) {
 	p := &Pkger{
 		infos: &maps.Infos{},
@@ -46,6 +49,7 @@ func New(her here.Info) (*Pkger, error) {
 	return p, nil
 }
 
+// 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.
 func (fx *Pkger) Create(name string) (pkging.File, error) {
 	name, err := fx.Abs(name)
 	if err != nil {
@@ -80,10 +84,12 @@ func (fx *Pkger) Create(name string) (pkging.File, error) {
 	return nf, nil
 }
 
+// Current returns the here.Info representing the current Pkger implementation.
 func (f *Pkger) Current() (here.Info, error) {
 	return f.Here, nil
 }
 
+// Info returns the here.Info of the here.Path
 func (f *Pkger) Info(p string) (here.Info, error) {
 	info, ok := f.infos.Load(p)
 	if ok {
@@ -98,6 +104,7 @@ func (f *Pkger) Info(p string) (here.Info, error) {
 	return info, 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.
 func (f *Pkger) MkdirAll(p string, perm os.FileMode) error {
 	p, err := f.Abs(p)
 	if err != nil {
@@ -106,6 +113,7 @@ func (f *Pkger) MkdirAll(p string, perm os.FileMode) error {
 	return os.MkdirAll(p, perm)
 }
 
+// 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.
 func (fx *Pkger) Open(name string) (pkging.File, error) {
 	pt, err := fx.Parse(name)
 	if err != nil {
@@ -142,10 +150,12 @@ func (fx *Pkger) Open(name string) (pkging.File, error) {
 	return nf, nil
 }
 
+// Parse the string in here.Path format.
 func (f *Pkger) Parse(p string) (here.Path, error) {
 	return f.Here.Parse(p)
 }
 
+// Stat returns a FileInfo describing the named file.
 func (f *Pkger) Stat(name string) (os.FileInfo, error) {
 	pt, err := f.Parse(name)
 	if err != nil {
@@ -167,6 +177,7 @@ func (f *Pkger) Stat(name string) (os.FileInfo, error) {
 	return info, nil
 }
 
+// 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.
 func (f *Pkger) Walk(p string, wf filepath.WalkFunc) error {
 	fp, err := f.Abs(p)
 	if err != nil {
@@ -198,6 +209,7 @@ func (f *Pkger) Walk(p string, wf filepath.WalkFunc) error {
 	return err
 }
 
+// Remove removes the named file or (empty) directory.
 func (fx *Pkger) Remove(name string) error {
 	name, err := fx.Abs(name)
 	if err != nil {
@@ -206,6 +218,7 @@ func (fx *Pkger) Remove(name string) error {
 	return os.Remove(name)
 }
 
+// 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).
 func (fx *Pkger) RemoveAll(name string) error {
 	name, err := fx.Abs(name)
 	if err != nil {