From 4e9c2f821eee3bebee7efb7cf79773de7cb13f7d Mon Sep 17 00:00:00 2001 From: Mark Bates Date: Wed, 16 Oct 2019 11:07:57 -0400 Subject: [PATCH] docs --- apply.go | 6 ++++++ apply_debug.go | 3 +++ doc.go | 21 --------------------- pkger.go | 5 +++++ pkging/mem/mem.go | 22 ++++++++++++++++------ pkging/mem/stuffing.go | 1 - pkging/pkger.go | 8 ++++++++ pkging/stdos/stdos.go | 13 +++++++++++++ 8 files changed, 51 insertions(+), 28 deletions(-) delete mode 100644 doc.go diff --git a/apply.go b/apply.go index cab8a66..733bcb2 100644 --- a/apply.go +++ b/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) diff --git a/apply_debug.go b/apply_debug.go index 9bc3ba1..1698861 100644 --- a/apply_debug.go +++ b/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 } diff --git a/doc.go b/doc.go deleted file mode 100644 index 01e48b4..0000000 --- a/doc.go +++ /dev/null @@ -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 diff --git a/pkger.go b/pkger.go index 80ae0a1..aae7067 100644 --- a/pkger.go +++ b/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) } diff --git a/pkging/mem/mem.go b/pkging/mem/mem.go index 57f7a32..9ee240b 100644 --- a/pkging/mem/mem.go +++ b/pkging/mem/mem.go @@ -17,12 +17,7 @@ import ( var _ pkging.Pkger = &Pkger{} -func WithInfo(fx *Pkger, infos ...here.Info) { - for _, info := range infos { - fx.infos.Store(info.ImportPath, info) - } -} - +// New returns *Pkger for the provided here.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() diff --git a/pkging/mem/stuffing.go b/pkging/mem/stuffing.go index b75b467..f9b73b4 100644 --- a/pkging/mem/stuffing.go +++ b/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 diff --git a/pkging/pkger.go b/pkging/pkger.go index 0729268..2a3d996 100644 --- a/pkging/pkger.go +++ b/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. diff --git a/pkging/stdos/stdos.go b/pkging/stdos/stdos.go index 73e93ad..787aac2 100644 --- a/pkging/stdos/stdos.go +++ b/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 {