package zip

Import Path
	golang.org/x/mod/zip (on go.dev)

Dependency Relation
	imports 13 packages, and imported by one package

Involved Source Files

	   d➜ zip.go
		Package zip provides functions for creating and extracting module zip files.

		Module zip files have several restrictions listed below. These are necessary
		to ensure that module zip files can be extracted consistently on supported
		platforms and file systems.

		• All file paths within a zip file must start with "<module>@<version>/",
		where "<module>" is the module path and "<version>" is the version.
		The module path must be valid (see golang.org/x/mod/module.CheckPath).
		The version must be valid and canonical (see
		golang.org/x/mod/module.CanonicalVersion). The path must have a major
		version suffix consistent with the version (see
		golang.org/x/mod/module.Check). The part of the file path after the
		"<module>@<version>/" prefix must be valid (see
		golang.org/x/mod/module.CheckFilePath).

		• No two file paths may be equal under Unicode case-folding (see
		strings.EqualFold).

		• A go.mod file may or may not appear in the top-level directory. If present,
		it must be named "go.mod", not any other case. Files named "go.mod"
		are not allowed in any other directory.

		• The total size in bytes of a module zip file may be at most MaxZipFile
		bytes (500 MiB). The total uncompressed size of the files within the
		zip may also be at most MaxZipFile bytes.

		• Each file's uncompressed size must match its declared 64-bit uncompressed
		size in the zip file header.

		• If the zip contains files named "<module>@<version>/go.mod" or
		"<module>@<version>/LICENSE", their sizes in bytes may be at most
		MaxGoMod or MaxLICENSE, respectively (both are 16 MiB).

		• Empty directories are ignored. File permissions and timestamps are also
		ignored.

		• Symbolic links and other irregular files are not allowed.

		Note that this package does not provide hashing functionality. See
		golang.org/x/mod/sumdb/dirhash.
Package-Level Type Names (total 8, in which 4 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type CheckedFiles (struct)
		CheckedFiles reports whether a set of files satisfy the name and size
		constraints required by module zip files. The constraints are listed in the
		package documentation.

		Functions that produce this report may include slightly different sets of
		files. See documentation for CheckFiles, CheckDir, and CheckZip for details.

		Fields (total 4, all are exported)
			Invalid []FileError
				Invalid is a list of files that should not be included in a module zip
				file, along with the reason each file is invalid.

			Omitted []FileError
				Omitted is a list of files that are ignored when creating a module zip
				file, along with the reason each file is ignored.

			SizeError error
				SizeError is non-nil if the total uncompressed size of the valid files
				exceeds the module zip size limit or if the zip file itself exceeds the
				limit.

			Valid []string
				Valid is a list of file paths that should be included in a zip file.

		Methods (only one, which is exported)
			( T) Err() error
				Err returns an error if CheckedFiles does not describe a valid module zip
				file. SizeError is returned if that field is set. A FileErrorList is returned
				if there are one or more invalid files. Other errors may be returned in the
				future.

		As Outputs Of (at least 5, in which 3 are exported)
			func CheckDir(dir string) (CheckedFiles, error)
			func CheckFiles(files []File) (CheckedFiles, error)
			func CheckZip(m module.Version, zipFile string) (CheckedFiles, error)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func checkFiles(files []File) (cf CheckedFiles, validFiles []File, validSizes []int64)
			func checkZip(m module.Version, f *os.File) (*zip.Reader, CheckedFiles, error)

	 type File (interface)
		File provides an abstraction for a file in a directory, zip, or anything
		else that looks like a file.

		Methods (total 3, all are exported)
			( T) Lstat() (os.FileInfo, error)
				Lstat returns information about the file. If the file is a symbolic link,
				Lstat returns information about the link itself, not the file it points to.

			( T) Open() (io.ReadCloser, error)
				Open provides access to the data within a regular file. Open may return
				an error if called on a directory or symbolic link.

			( T) Path() string
				Path returns a clean slash-separated relative path from the module root
				directory to the file.

		Implemented By (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			 dirFile
		As Outputs Of (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func checkFiles(files []File) (cf CheckedFiles, validFiles []File, validSizes []int64)
			func listFilesInDir(dir string) (files []File, omitted []FileError, err error)
		As Inputs Of (at least 3, in which 2 are exported)
			func CheckFiles(files []File) (CheckedFiles, error)
			func Create(w io.Writer, m module.Version, files []File) (err error)
			/* at least one unexported ... *//* at least one unexported: */
			func checkFiles(files []File) (cf CheckedFiles, validFiles []File, validSizes []int64)

	 type FileError (struct)

		Fields (total 2, both are exported)
			Err error
			Path string
		Methods (total 2, both are exported)
			( T) Error() string
			( T) Unwrap() error
		Implements (at least 2, both are exported)
			 T : golang.org/x/xerrors.Wrapper
			 T : error
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func listFilesInDir(dir string) (files []File, omitted []FileError, err error)

	 type FileErrorList ([]T)

		Methods (only one, which is exported)
			( T) Error() string
		Implements (at least one exported)
			 T : error

	/* 4 unexporteds ... *//* 4 unexporteds: */
	 type collisionChecker (map)
		collisionChecker finds case-insensitive name collisions and paths that
		are listed as both files and directories.

		The keys of this map are processed with strToFold. pathInfo has the original
		path for each folded path.

		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			( T) check(p string, isDir bool) error

	 type dirFile (struct)

		Fields (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			filePath string
			info os.FileInfo
			slashPath string
		Methods (total 3, all are exported)
			( T) Lstat() (os.FileInfo, error)
			( T) Open() (io.ReadCloser, error)
			( T) Path() string
		Implements (at least one exported)
			 T : File

	 type pathInfo (struct)

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			isDir bool
			path string

	 type zipError (struct)

		Fields (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			err error
			path string
			verb string
		Methods (total 2, both are exported)
			(*T) Error() string
			(*T) Unwrap() error
		Implements (at least 2, both are exported)
			*T : golang.org/x/xerrors.Wrapper
			*T : error


Package-Level Functions (total 11, in which 6 are exported)

	 func CheckDir(dir string) (CheckedFiles, error)
		CheckDir reports whether the files in dir satisfy the name and size
		constraints listed in the package documentation. The returned CheckedFiles
		record contains lists of valid, invalid, and omitted files. If a directory is
		omitted (for example, a nested module or vendor directory), it will appear in
		the omitted list, but its files won't be listed.

		CheckDir returns an error if it encounters an I/O error or if the returned
		CheckedFiles does not describe a valid module zip file (according to
		CheckedFiles.Err). The returned CheckedFiles is still populated when such
		an error is returned.

		Note that CheckDir will not open any files, so CreateFromDir may still fail
		when CheckDir is successful due to I/O errors.

	 func CheckFiles(files []File) (CheckedFiles, error)
		CheckFiles reports whether a list of files satisfy the name and size
		constraints listed in the package documentation. The returned CheckedFiles
		record contains lists of valid, invalid, and omitted files. Every file in
		the given list will be included in exactly one of those lists.

		CheckFiles returns an error if the returned CheckedFiles does not describe
		a valid module zip file (according to CheckedFiles.Err). The returned
		CheckedFiles is still populated when an error is returned.

		Note that CheckFiles will not open any files, so Create may still fail when
		CheckFiles is successful due to I/O errors and reported size differences.

	 func CheckZip(m module.Version, zipFile string) (CheckedFiles, error)
		CheckZip reports whether the files contained in a zip file satisfy the name
		and size constraints listed in the package documentation.

		CheckZip returns an error if the returned CheckedFiles does not describe
		a valid module zip file (according to CheckedFiles.Err). The returned
		CheckedFiles is still populated when an error is returned. CheckZip will
		also return an error if the module path or version is malformed or if it
		encounters an error reading the zip file.

		Note that CheckZip does not read individual files, so Unzip may still fail
		when CheckZip is successful due to I/O errors.

	 func Create(w io.Writer, m module.Version, files []File) (err error)
		Create builds a zip archive for module m from an abstract list of files
		and writes it to w.

		Create verifies the restrictions described in the package documentation
		and should not produce an archive that Unzip cannot extract. Create does not
		include files in the output archive if they don't belong in the module zip.
		In particular, Create will not include files in modules found in
		subdirectories, most files in vendor directories, or irregular files (such
		as symbolic links) in the output archive.

	 func CreateFromDir(w io.Writer, m module.Version, dir string) (err error)
		CreateFromDir creates a module zip file for module m from the contents of
		a directory, dir. The zip content is written to w.

		CreateFromDir verifies the restrictions described in the package
		documentation and should not produce an archive that Unzip cannot extract.
		CreateFromDir does not include files in the output archive if they don't
		belong in the module zip. In particular, CreateFromDir will not include
		files in modules found in subdirectories, most files in vendor directories,
		or irregular files (such as symbolic links) in the output archive.
		Additionally, unlike Create, CreateFromDir will not include directories
		named ".bzr", ".git", ".hg", or ".svn".

	 func Unzip(dir string, m module.Version, zipFile string) (err error)
		Unzip extracts the contents of a module zip file to a directory.

		Unzip checks all restrictions listed in the package documentation and returns
		an error if the zip archive is not valid. In some cases, files may be written
		to dir before an error is returned (for example, if a file's uncompressed
		size does not match its declared size).

		dir may or may not exist: Unzip will create it and any missing parent
		directories if it doesn't exist. If dir exists, it must be empty.

	/* 5 unexporteds ... *//* 5 unexporteds: */
	 func checkFiles(files []File) (cf CheckedFiles, validFiles []File, validSizes []int64)
		checkFiles implements CheckFiles and also returns lists of valid files and
		their sizes, corresponding to cf.Valid. These lists are used in Crewate to
		avoid repeated calls to File.Lstat.

	 func checkZip(m module.Version, f *os.File) (*zip.Reader, CheckedFiles, error)
		checkZip implements checkZip and also returns the *zip.Reader. This is
		used in Unzip to avoid redundant I/O.

	 func isVendoredPackage(name string) bool
		isVendoredPackage attempts to report whether the given filename is contained
		in a package whose import path contains (but does not end with) the component
		"vendor".

		Unfortunately, isVendoredPackage reports false positives for files in any
		non-top-level package whose import path ends in "vendor".

	 func listFilesInDir(dir string) (files []File, omitted []FileError, err error)
		listFilesInDir walks the directory tree rooted at dir and returns a list of
		files, as well as a list of directories and files that were skipped (for
		example, nested modules and symbolic links).

	 func strToFold(s string) string
		strToFold returns a string with the property that
			strings.EqualFold(s, t) iff strToFold(s) == strToFold(t)
		This lets us test a large set of strings for fold-equivalent
		duplicates without making a quadratic number of calls
		to EqualFold. Note that strings.ToUpper and strings.ToLower
		do not have the desired property in some corner cases.


Package-Level Variables (total 12, none are exported)

	/* 12 unexporteds ... *//* 12 unexporteds: */
	  var errGoModCase error
	  var errGoModSize error
	  var errHgArchivalTxt error
	  var errLICENSESize error
	  var errNotRegular error
	  var errPathNotClean error
		Predefined error messages for invalid files. Not exhaustive.

	  var errPathNotRelative error
	  var errSubmoduleDir error
	  var errSubmoduleFile error
	  var errSymlink error
	  var errVCS error
		Predefined error messages for omitted files. Not exhaustive.

	  var errVendored error
Package-Level Constants (total 3, all are exported)

	const MaxGoMod = 16777216
		MaxGoMod is the maximum size in bytes of a go.mod file within a
		module zip file.

	const MaxLICENSE = 16777216
		MaxLICENSE is the maximum size in bytes of a LICENSE file within a
		module zip file.

	const MaxZipFile = 524288000
		MaxZipFile is the maximum size in bytes of a module zip file. The
		go command will report an error if either the zip file or its extracted
		content is larger than this.

The pages are generated with Golds v0.3.2-preview. (GOOS=darwin GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.