resources-go.v2: Index | Files | Directories

package resources

import ""

Package resources provides resource loading for applications.

Data can be loaded from a user-provided search path whose elements may be:

- File system locations
- The application's current working directory
- The application's containing directory
- The package's source-code directory
- A zip file
- A zip file embedded in the executable

Source code can be found at


Package Files

auto.go doc.go errors.go file.go package.go resources.go sequence.go util.go zip.go zipexe.go


var (
    ErrNotFound    error = errors.New("resources: resource not found")
    ErrEscapeRoot  error = errors.New("resources: path escapes root")
    ErrNotRelative error = errors.New("resources: path not relative")

func CheckPath Uses

func CheckPath(path string) error

CheckPath() returns nil if given a valid path. Valid paths are forward slash delimeted, relative paths, which don't escape the base-level directory.

Otherwise it returns one of the following error types:

- ErrEscapeRoot: if the path leaves the base directory
- ErrNotRelative: if the path is not a relative path

func ExecutablePath Uses

func ExecutablePath() (string, error)

ExecutablePath returns a system-native path to the currently running executable.

NOTE: this function was intended to dissapear when it's functionality would be handled by the stdlib (go issue 4057). Since that is less likely to happen, I will probably leave this here leaving the API alone. It is supported via the "" package.

func IsNotFound Uses

func IsNotFound(e error) bool

IsNotFound returns true if the error given is an error representing a Resource that was not found.

func Open Uses

func Open(path string) (io.ReadCloser, error)

Open() is a shortcut for DefaultBundle.Open()

type Bundle Uses

type Bundle interface {
    // Opens a resource for reading at path.
    // Returns ErrNotFound if file doesn't exist.
    Open(path string) (io.ReadCloser, error)

    // Release any os-resources needed to maintain bundle
    Close() error

A Bundle represents a collection of resources that can be streamed. The simple bundle only allows opening of known files, no searching or listing allowed.

Paths to resources in bundles are platform independant, and should have directories delimeted by forward-slashes.

Bundles provide a close method to release any os-resources they could be holding onto.

func OpenAutoBundle Uses

func OpenAutoBundle(f func() (Bundle, error)) Bundle

func OpenCurrentPackage Uses

func OpenCurrentPackage() (Bundle, error)

Opens the source directory of the current package as a Bundle. The current package is the package of the code calling OpenCurrentPackage() (as determined by runtime.Caller())

func OpenFS Uses

func OpenFS(base_dir string) Bundle

func OpenPackage Uses

func OpenPackage(import_path string) (Bundle, error)

OpenPackagePath returns a Bundle which accesses files in the source directory of the package named by the given import path.

Bundles accessing packages support the Searcher and Lister interfaces.

func OpenZip Uses

func OpenZip(path string) (Bundle, error)

Opens a zipfile on disk as a bundle. You must call Close() to release the open file handle.

Zip files opened as bundles implement the Bundle, Searcher, and Lister interfaces.

If the file is in a known executable format, it is searched for an embedded zip file.

func OpenZipReader Uses

func OpenZipReader(rda io.ReaderAt, size int64) (Bundle, error)

Opens a zipfile specified by the given ReaderAt and size. Close() is a no-op on the returned structure, ie: you must close the reader's resource yourself if necessary.

Zip files opened as bundles implement the Bundle, Searcher, and Lister interfaces.

If the reader accesses data for a known executable format, it will be searched for an embedded zip file.

type BundleSequence Uses

type BundleSequence []Bundle

BundleSequences are meta-bundles which contain a slice of sub-bundles to test/access sequentially for resources.

Nil bundles are skipped, instead of causing errors or panics.

var DefaultBundle BundleSequence

DefaultBundle represents a default search path of:

- The current working directory
- The directory containing the executable
- The package source-code directory
- The executable treated as a ZipBundle

func (BundleSequence) Close Uses

func (bs BundleSequence) Close() error

Close() is a no-op for BundleSequences; you must close the sub-bundles yourself.

func (BundleSequence) Find Uses

func (bs BundleSequence) Find(path string) (Resource, error)

Find finds the first resource matching path in the sub-bundles. If multiple sub-bundles contain a resource a the given path, the resource from the earliest bundle is used.

If any error other than ErrNotFound is seen, it is returned.

func (BundleSequence) Glob Uses

func (bs BundleSequence) Glob(pattern string) (matches []Resource, err error)

Glob finds the collection of all resources in all the sub-bundles which match the given glob pattern. In the event that multiple resources matched have the same path, the one from the earliest sub-bundle will be shown, all others will be suppressed.

func (BundleSequence) List Uses

func (bs BundleSequence) List() (resources []Resource, err error)

List provides a slice containing all resources from all the sub-bundles. Should multiple bundles contain a resource at the same path, only the first resource (from the first sub-bundle) will be present in the list.

func (BundleSequence) Open Uses

func (bs BundleSequence) Open(path string) (io.ReadCloser, error)

Open finds the first sub-bundle where Open() doesn't return a ErrNotFound, and returns the io.ReadCloser.

If any error other than ErrNotFound is seen, it is returned immediately.

type Lister Uses

type Lister interface {
    List() ([]Resource, error)

A Lister represents an object with a list of resources that can be iterated over.

type Resource Uses

type Resource interface {
    // Open the resource for reading.
    // Returns ErrNotFound if file missing.
    Open() (io.ReadCloser, error)

    // Get file information about the resource
    Stat() (os.FileInfo, error)

    // Get the platform independent path for this resource
    Path() string

A Resource represents a streamable resource that has not yet been opened, but has been found in a searchable or listable bundle.

Many bundle type have volatile resources, therefore in most cases Resource.Open must be checked for errors. (ie: There is no guarantee that the resource still exists between the call to Find/Glob/List and opening it)

func Find Uses

func Find(path string) (Resource, error)

Find() is a shortcut for DefaultBundle.Find()

func Glob Uses

func Glob(pattern string) ([]Resource, error)

Glob() is a shortcut for DefaultBundle.Glob()

func List Uses

func List() ([]Resource, error)

List() is a shortcut for DefaultBundle.List()

type Searcher Uses

type Searcher interface {
    // Returns a Resource at the given path.
    // Returns ErrNotFound if no file exists.
    Find(path string) (Resource, error)

    // Returns all Resources matching the
    // given glob pattern.
    Glob(pattern string) ([]Resource, error)

A Searcher represents an object where exact (Find) and pattern based (Glob) searches for resources can be made. The results of these operations are unopened Resources.



Package resources imports 12 packages (graph) and is imported by 11 packages. Updated 2018-03-02. Refresh now. Tools for package owners.