Documentation
¶
Index ¶
Constants ¶
const ( SemverMajor = 3 SemverMinor = 0 SemverRevision = 0 )
..
const ( NoCompression = flate.NoCompression BestSpeed = flate.BestSpeed BestCompression = flate.BestCompression DefaultCompression = flate.BestSpeed HuffmanOnly = flate.HuffmanOnly )
Compression constants are defined here and copied from the standard library flate package so that code importing vpkg does not need to also import flate.
The compression levels dictate how much work should be done to compress the contents of a package. Values other that those defined in these constants are acceptable, see the flate package documentation for for information.
const Suffix = ".vorteil"
Suffix is the canonical file-extension given to Vorteil package files.
Variables ¶
var ErrNotAPackage = errors.New("not a valid package")
ErrNotAPackage is returned when attempting to extract the contents of a file that not a Vorteil package, or at least is broken or corrupt.
var ErrVersionNotSupported = fmt.Errorf("package version not supported (require version %v.x.x)", SupportedPackageMajor)
ErrVersionNotSupported is returned when attempting to read an unsupported Vorteil package version.
var (
SupportedPackageMajor = 3
)
..
Functions ¶
Types ¶
type Builder ¶
type Builder interface {
Close() error
// Pack writes the Vorteil package to the provided
// io.Writer.
Pack(w io.Writer) error
// SetCompressionLevel is an advanced function that
// can be used to adjust the amount of compression
// that is done to the contents of the Vorteil
// package. The default is DefaultCompression.
SetCompressionLevel(level int)
// SetMonitoringOptions is an advanced function that
// can be used to add logging and progress reporting
// to packaging operations, in addition to other
// possible uses. See the documentation for the
// MonitoringOptions object for more information.
SetMonitoringOptions(opts MonitoringOptions)
// SetVCFG takes the provided vio.File and uses it
// as the vcfg for the package, overwriting any
// previously existing vcfg.
//
// Note: this is NOT a vcfg merge operation. It
// completely supercedes previous existing vcfgs.
SetVCFG(f vio.File) error
MergeVCFG(cfg *vcfg.VCFG) error
// SetIcon takes the provided vio.File and uses it
// as the icon for the package, overwriting any
// previously existing icon.
SetIcon(f vio.File) error
// RemoveFromFS removes a single filesystem mapping
// from the package.
RemoveFromFS(path string) error
// AddToFS takes the single vio.File and maps it
// into the filesystem for the package, replacing
// anything it conflicts with and automatically
// creating parent directories on demand if required.
//
// Absolute and relative paths are both acceptable,
// with relative paths being relative to the root
// directory of the filesystem. For example, the
// following are all equivalent:
//
// dir/file
// /dir/file
// ./dir/file
AddToFS(path string, f vio.File) error
// AddSubTreeToFS takes an entire vio.FileTree
// and maps it into the filesystem for the package,
// replacing anything it conflicts with and
// automatically creating parent directories on
// demand if required.
//
// Absolute and relative paths are both acceptable,
// with relative paths being relative to the root
// directory of the filesystem. For example, the
// following are all equivalent:
//
// dir/file
// /dir/file
// ./dir/file
AddSubTreeToFS(path string, sub vio.FileTree) error
}
Builder defines a class of object that can be used to organize and then construct the contents of a new Vorteil package.
func NewBuilder ¶
func NewBuilder() Builder
NewBuilder returns an implementation of the Builder interface. The returned Builder will have an empty filesystem and no defined binary, vcfg, or icon. At a minimum, the Builder.SetBinary and Builder.SetVCFG functions must each be called once before the Builder.Pack function to constitute a valid and complete package.
func NewBuilderFromReader ¶
NewBuilderFromReader returns an implementation of the Builder interface with all of its internal components initialized to the values stored within an existing Vorteil package, as found in a Reader.
If no further changes are made to the Builder or Reader, this package guarantees that the output of its Builder.Pack function will be identical to the input for the Load function that created the Reader.
type MonitoringOptions ¶
type MonitoringOptions struct {
PreProcessCompleteCallback func(report PreProcessReport) error
NextFileCallback func(path string, fi os.FileInfo) error
PreCompressionWriter io.Writer
}
MonitoringOptions contains optional fields that may be provided in a call to Builder.SetMonitoringOptions to receive live information about a pack operation as it occurs.
The PreProcessCompleteCallback, if provided, will be called precisely once. It will be called before anything is written to the PreCompressionWriter, and before any calls to the NextFileCallback. It provides the callback with information it has compiled about the contents of the Builder such as the total size of the uncompressed package, which can be helpful for keeping live progress tracking. If an error is returned the Builder.Pack function will fail, which means this callback can also be used to cancel a job if the PreProcessReport is unacceptable. If left nil, no such information is compiled and the Builder.Pack operation will be faster.
NextFileCallback will be called once for each file and directory within the package. It is called just before that file is added to the archive, and provides information that can be used to report specifically what part of the packaging process the Builder.Pack logic has reached at any time. If an error is returned the Builder.Pack function will fail, which means this callback can also be used to cancel a job.
If not nil, all data written to the package will be cloned to the PreCompressionWriter, uncompressed. The main forseen use for this is to track byte-by-byte how far along the complete Builder.Pack operation has come. Errors returned by the PreCompressionWriter will cause the Builder.Pack operation to fail, which means this writer can also be used to cancel a job.
type PreProcessReport ¶
PreProcessReport contains information compiled by the packaging logic about an upcoming pack operation, before the packing actually begins. It is used only as an argument to the callback function at MonitoringOptions.PreProcessCompleteCallback, and is useful for initializing things like progress bars.
type Reader ¶
type Reader interface {
// VCFG returns a vio.File object containing the
// complete Vorteil configuration settings to be
// used with the application.
VCFG() vio.File
// Icon returns a vio.File object containing a
// picture file used as an icon representing the
// package and application.
//
// This function will always returns a valid vio.File,
// but packages commonly will not have an icon and
// the calling logic should check the length of this
// file (which will be zero in this circumstance) to
// understand if an icon actually exists for the
// package.
Icon() vio.File
// FS returns a vio.FileTree object representing
// the total contents of the main filesystem on the
// app's virtual disk.
FS() vio.FileTree
Close() error
}
Reader defines a class of object that can be used to read specific information from a Vorteil package.
func Load ¶
Load extracts information from the provided io.Reader and turns it into an implementation of the Reader interface, if the reader is a stream of valid Vorteil package data.
This function loads information from the reader lazily, and in a predictable order that can be exploited by properly designed logic to minimize the amount of ram caching required without ever using temporary files.
Because the Reader is loaded lazily, the provided io.Reader must remain valid for the lifetime of the Reader. If the provided io.Reader is also an io.Closer, it should NOT be closed until the reader is no longer required.
The lazy loading won't necessarily consume the entire contents of the io.Reader up until EOF unless the calling logic makes use of the entire contents of the package. If it is important to consume the entire stream, you may want to io.Copy(ioutil.Discard, r) before closing it.
Source Files