filesys

type HashVerifier interface {
	hash.Hash

	// Match reports whether the current hash (as returned by Sum(nil))
	// matches the pre-specified prefix.
	Match() bool
}

type ReadOptions struct {
	// Size of the buffer for reading the file at least.
	// Non-positive values for using default value.
	BufSize int

	// Offset of the file to read, in bytes,
	// relative to the origin of the file for positive values,
	// and relative to the end of the file for negative values.
	Offset int64

	// Limit of the file to read, in bytes.
	// Non-positive values for no limit.
	Limit int64

	// True if not to decompress when the file is compressed by gzip or bzip2,
	// and not to restore when the file is archived by tar (i.e., tape archive).
	Raw bool

	// A method-decompressor map for reading the ZIP archive.
	// These decompressors are registered to the archive/zip.Reader.
	// (Nil decompressors are ignored.)
	//
	// Package archive/zip has two built-in decompressors for the common methods
	// archive/zip.Store (0) and archive/zip.Deflate (8).
	//
	// For more details, see the documentation of the method
	// RegisterDecompressor of archive/zip.Reader and
	// the function archive/zip.RegisterDecompressor.
	ZipDcomp map[uint16]zip.Decompressor

	// A function that wraps the reader to io.ReaderAt
	// to create an archive/zip.Reader.
	//
	// It also returns the size that can be read, and any error encountered.
	//
	// It will only be called when the reader does not implement io.ReaderAt.
	ZipReaderAtFunc func(r io.Reader) (ra io.ReaderAt, size int64, err error)
}

type Reader interface {
	inout.Closer
	inout.BufferedReader

	// TarEnabled returns true if the file is archived by tar
	// (i.e., tape archive) and is not opened in raw mode.
	TarEnabled() bool

	// TarNext advances to the next entry in the tar archive.
	//
	// The tar.Header.Size determines how many bytes can be read
	// for the next file.
	// Any remaining data in current file is automatically discarded.
	//
	// io.EOF is returned at the end of the input.
	//
	// If the file is not archived by tar or is opened in raw mode,
	// it does nothing and reports ErrNotTar.
	// (To test whether err is ErrNotTar, use function errors.Is.)
	TarNext() (hdr *tar.Header, err error)

	// ZipEnabled returns true if the file is archived by ZIP
	// and is not opened in raw mode.
	ZipEnabled() bool

	// ZipOpen opens the file with specified name in the ZIP archive.
	//
	// The name must be a relative path: it must not start with a drive letter
	// (e.g., "C:") or leading slash. Only forward slashes are allowed;
	// "../" elements and trailing slashes (e.g., "a/") are not allowed.
	//
	// If the reader's file is not archived by ZIP or is opened in raw mode,
	// it does nothing and reports ErrNotZip.
	// (To test whether the error is ErrNotZip, use function errors.Is.)
	ZipOpen(name string) (file fs.File, err error)

	// ZipFiles returns the files in the ZIP archive, sorted by filename.
	//
	// If the reader's file is not archived by ZIP or is opened in raw mode,
	// it does nothing and reports ErrNotZip.
	// (To test whether the error is ErrNotZip, use function errors.Is.)
	ZipFiles() (files []*zip.File, err error)

	// ZipComment returns the end-of-central-directory comment field
	// of the ZIP archive.
	//
	// If the reader's file is not archived by ZIP or is opened in raw mode,
	// it does nothing and reports ErrNotZip.
	// (To test whether the error is ErrNotZip, use function errors.Is.)
	ZipComment() (comment string, err error)

	// Options returns a copy of options used by this reader.
	Options() *ReadOptions

	// FileStat returns the io/fs.FileInfo structure describing file.
	FileStat() (info fs.FileInfo, err error)
}

type WritableFile interface {
	io.WriteCloser

	// Stat returns the io/fs.FileInfo structure describing file.
	Stat() (info fs.FileInfo, err error)
}

type WriteOptions struct {
	// Size of the buffer for writing the file at least.
	// Non-positive values for using default value.
	BufSize int

	// True if not to compress the file with gzip and not to archive the file
	// with tar (i.e., tape archive) according to the file extension.
	Raw bool

	// The compression level of DEFLATE.
	// It should be in the range [-2, 9].
	// The zero value (0) stands for no compression
	// other than the default value.
	// To use the default value, set it to compress/flate.DefaultCompression.
	// For more details, see the documentation of compress/flate.NewWriter.
	//
	// This option only takes effect when DEFLATE compression is applied.
	// That is, when Raw is false, and the file extension is ".gz" or ".tgz",
	// or ".zip" and the ZIP archive uses DEFLATE compression.
	DeflateLv int

	// The offset of the beginning of the ZIP data within the underlying writer.
	// It should be used when the ZIP data is appended to an existing file,
	// such as a binary executable.
	//
	// Non-positive values are ignored.
	ZipOffset int64

	// The end-of-central-directory comment field of the ZIP archive.
	// It should be 65535 bytes at most.
	// If the comment is too long, an error is reported.
	ZipComment string

	// A method-compressor map for writing the ZIP archive.
	// These compressors are registered to the archive/zip.Writer.
	// (Nil compressors are ignored.)
	//
	// Package archive/zip has two built-in compressors for the common methods
	// archive/zip.Store (0) and archive/zip.Deflate (8).
	//
	// For more details, see the documentation of the method RegisterCompressor
	// of archive/zip.Writer and the function archive/zip.RegisterCompressor.
	ZipComp map[uint16]zip.Compressor
}

type Writer interface {
	inout.Closer
	inout.BufferedWriter

	// TarEnabled returns true if the file is archived by tar
	// (i.e., tape archive) and is not opened in raw mode.
	TarEnabled() bool

	// TarWriteHeader writes hdr and prepares to accept the content of
	// the next file.
	//
	// The tar.Header.Size determines how many bytes can be written for
	// the next file.
	// If the current file is not fully written, it returns an error.
	// It implicitly flushes any padding necessary before writing the header.
	//
	// If the file is not archived by tar or is opened in raw mode,
	// it does nothing and reports ErrNotTar.
	// (To test whether the error is ErrNotTar, use function errors.Is.)
	TarWriteHeader(hdr *tar.Header) error

	// TarAddFS adds the files from the specified filesystem
	// to the tape archive.
	// It walks the directory tree starting at the root of the filesystem
	// adding each file to the tape archive
	// while maintaining the directory structure.
	//
	// If the file is not archived by tar or is opened in raw mode,
	// it does nothing and reports ErrNotTar.
	// (To test whether the error is ErrNotTar, use function errors.Is.)
	TarAddFS(fsys fs.FS) error

	// ZipEnabled returns true if the file is archived by ZIP
	// and is not opened in raw mode.
	ZipEnabled() bool

	// ZipCreate adds a file with specified name to the ZIP archive and
	// switches the writer to that file.
	//
	// The file contents are compressed with DEFLATE.
	//
	// The name must be a relative path: it must not start with a drive letter
	// (e.g., "C:") or leading slash. Only forward slashes are allowed;
	// "../" elements are not allowed.
	// To create a directory instead of a file, add a trailing slash
	// to the name (e.g., "dir/").
	//
	// The file's contents must be written to the writer before the next call
	// to ZipCreate, ZipCreateHeader, ZipCreateRaw, ZipCopy, or Close.
	//
	// If the writer's file is not archived by ZIP or is opened in raw mode,
	// it does nothing and reports ErrNotZip.
	// (To test whether the error is ErrNotZip, use function errors.Is.)
	ZipCreate(name string) error

	// ZipCreateHeader adds a file to the ZIP archive using the specified
	// file header for the file metadata and switches the writer to that file.
	//
	// The writer takes ownership of fh and may mutate its fields.
	// The client must not modify fh after calling ZipCreateHeader.
	//
	// The file's contents must be written to the writer before the next call
	// to ZipCreate, ZipCreateHeader, ZipCreateRaw, ZipCopy, or Close.
	//
	// If the writer's file is not archived by ZIP or is opened in raw mode,
	// it does nothing and reports ErrNotZip.
	// (To test whether the error is ErrNotZip, use function errors.Is.)
	ZipCreateHeader(fh *zip.FileHeader) error

	// ZipCreateRaw is like ZipCreateHeader,
	// but the bytes passed to the writer are not compressed.
	ZipCreateRaw(fh *zip.FileHeader) error

	// ZipCopy copies the file f (obtained from an archive/zip.Reader)
	// into the writer.
	//
	// It copies the raw form directly bypassing
	// decompression, compression, and validation.
	//
	// If the writer's file is not archived by ZIP or is opened in raw mode,
	// it does nothing and reports ErrNotZip.
	// (To test whether the error is ErrNotZip, use function errors.Is.)
	ZipCopy(f *zip.File) error

	// ZipAddFS adds the files from the specified filesystem
	// to the ZIP archive.
	// It walks the directory tree starting at the root of the filesystem
	// adding each file to the ZIP using deflate
	// while maintaining the directory structure.
	//
	// If the writer's file is not archived by ZIP or is opened in raw mode,
	// it does nothing and reports ErrNotZip.
	// (To test whether the error is ErrNotZip, use function errors.Is.)
	ZipAddFS(fsys fs.FS) error

	// Options returns a copy of options used by this writer.
	Options() *WriteOptions

	// FileStat returns the io/fs.FileInfo structure describing file.
	FileStat() (info fs.FileInfo, err error)
}