vfs

package module
v0.0.0-...-71278df Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 16, 2023 License: MIT Imports: 18 Imported by: 1

README

vfsgen

Build Status GoDoc

Package vfsgen takes an http.FileSystem (likely at go generate time) and generates Go code that statically implements the provided http.FileSystem.

Features:

  • Efficient generated code without unneccessary overhead.

  • Uses gzip compression internally (selectively, only for files that compress well).

  • Enables direct access to internal gzip compressed bytes via an optional interface.

  • Outputs gofmted Go code.

Installation

go get -u github.com/gozelle/vfs

Usage

Package vfsgen is a Go code generator library. It has a Generate function that takes an input filesystem (as a http.FileSystem type), and generates a Go code file that statically implements the contents of the input filesystem.

For example, we can use http.Dir as a http.FileSystem implementation that uses the contents of the /path/to/assets directory:

var fs http.FileSystem = http.Dir("/path/to/assets")

Now, when you execute the following code:

err := vfsgen.Generate(fs, vfsgen.Options{})
if err != nil {
	log.Fatalln(err)
}

An assets_vfsdata.go file will be generated in the current directory:

// Code generated by vfsgen; DO NOT EDIT.

package main

import ...

// assets statically implements the virtual filesystem provided to vfsgen.Generate.
var assets http.FileSystem = ...

Then, in your program, you can use assets as any other http.FileSystem, for example:

file, err := assets.Open("/some/file.txt")
if err != nil {
	return err
}
defer file.Close()

http.Handle("/assets/", http.FileServer(assets))

vfsgen can be more useful when combined with build tags and go generate directives. This is described below.

go generate Usage

vfsgen is great to use with go generate directives. The code invoking vfsgen.Generate can go in an assets_generate.go file, which can then be invoked via "//go:generate go run assets_generate.go". The input virtual filesystem can read directly from disk, or it can be more involved.

By using build tags, you can create a development mode where assets are loaded directly from disk via http.Dir, but then statically implemented for final releases.

For example, suppose your source filesystem is defined in a package with import path "example.com/project/data" as:

// +build dev

package data

import "net/http"

// Assets contains project assets.
var Assets http.FileSystem = http.Dir("assets")

When built with the "dev" build tag, accessing data.Assets will read from disk directly via http.Dir.

A generate helper file assets_generate.go can be invoked via "//go:generate go run -tags=dev assets_generate.go" directive:

// +build ignore

package main

import (
	"log"

	"example.com/project/data"
	"github.com/gozelle/vfs"
)

func main() {
	err := vfsgen.Generate(data.Assets, vfsgen.Options{
		PackageName:  "data",
		BuildTags:    "!dev",
		VariableName: "Assets",
	})
	if err != nil {
		log.Fatalln(err)
	}
}

Note that "dev" build tag is used to access the source filesystem, and the output file will contain "!dev" build tag. That way, the statically implemented version will be used during normal builds and go get, when custom builds tags are not specified.

vfsgendev Usage

vfsgendev is a binary that can be used to replace the need for the assets_generate.go file.

Make sure it's installed and available in your PATH.

go get -u github.com/gozelle/vfs/cmd/vfsgendev

Then the "//go:generate go run -tags=dev assets_generate.go" directive can be replaced with:

//go:generate vfsgendev -source="example.com/project/data".Assets

vfsgendev accesses the source variable using "dev" build tag, and generates an output file with "!dev" build tag.

Additional Embedded Information

All compressed files implement httpgzip.GzipByter interface for efficient direct access to the internal compressed bytes:

// GzipByter is implemented by compressed files for
// efficient direct access to the internal compressed bytes.
type GzipByter interface {
	// GzipBytes returns gzip compressed contents of the file.
	GzipBytes() []byte
}

Files that have been determined to not be worth gzip compressing (their compressed size is larger than original) implement httpgzip.NotWorthGzipCompressing interface:

// NotWorthGzipCompressing is implemented by files that were determined
// not to be worth gzip compressing (the file size did not decrease as a result).
type NotWorthGzipCompressing interface {
	// NotWorthGzipCompressing is a noop. It's implemented in order to indicate
	// the file is not worth gzip compressing.
	NotWorthGzipCompressing()
}

Comparison

vfsgen aims to be conceptually simple to use. The http.FileSystem abstraction is central to vfsgen. It's used as both input for code generation, and as output in the generated code.

That enables great flexibility through orthogonality, since helpers and wrappers can operate on http.FileSystem without knowing about vfsgen. If you want, you can perform pre-processing, minifying assets, merging folders, filtering out files and otherwise modifying input via generic http.FileSystem middleware.

It avoids unneccessary overhead by merging what was previously done with two distinct packages into a single package.

It strives to be the best in its class in terms of code quality and efficiency of generated code. However, if your use goals are different, there are other similar packages that may fit your needs better.

Alternatives
  • go-bindata - Reads from disk, generates Go code that provides access to data via a custom API.
  • go-bindata-assetfs - Takes output of go-bindata and provides a wrapper that implements http.FileSystem interface (the same as what vfsgen outputs directly).
  • becky - Embeds assets as string literals in Go source.
  • statik - Embeds a directory of static files to be accessed via http.FileSystem interface (sounds very similar to vfsgen); implementation sourced from camlistore.
  • go.rice - Makes working with resources such as HTML, JS, CSS, images and templates very easy.
  • esc - Embeds files into Go programs and provides http.FileSystem interfaces to them.
  • staticfiles - Allows you to embed a directory of files into your Go binary.
  • togo - Generates a Go source file with a []byte var containing the given file's contents.
  • fileb0x - Simple customizable tool to embed files in Go.
  • embedfiles - Simple tool for embedding files in Go code as a map.
  • packr - Simple solution for bundling static assets inside of Go binaries.
  • rsrc - Tool for embedding .ico & manifest resources in Go programs for Windows.

Attribution

This package was originally based on the excellent work by @jteeuwen on go-bindata and @elazarl on go-bindata-assetfs.

License

Documentation

Overview

Package vfsgen takes an http.FileSystem (likely at `go generate` time) and generates Go code that statically implements the provided http.FileSystem.

Features:

- Efficient generated code without unneccessary overhead.

- Uses gzip compression internally (selectively, only for files that compress well).

- Enables direct access to internal gzip compressed bytes via an optional interface.

- Outputs `gofmt`ed Go code.

Example

This code will generate an assets_vfsdata.go file with `var assets http.FileSystem = ...` that statically implements the contents of "assets" directory.

vfsgen is great to use with go generate directives. This code can go in an assets_gen.go file, which can then be invoked via "//go:generate go run assets_gen.go". The input virtual filesystem can read directly from disk, or it can be more involved. 

package main

import (
	"github.com/gozelle/vfs"
	"log"
	"net/http"
)

func main() {
	var fs http.FileSystem = http.Dir("assets")

	err := vfs.Generate(fs, vfs.Options{})
	if err != nil {
		log.Fatalln(err)
	}
}

Output:

Index

Examples

Constants

This section is empty.

Variables

View Source 
var SkipDir error = fsi.SkipDir

Functions

func Generate 

func Generate(input http.FileSystem, opt Options) error

Generate Go code that statically implements input filesystem, write the output to a file specified in opt.

func Proxy 

func Proxy(dir string) http.FileSystem

func Walk 

func Walk(fs http.FileSystem, root string, fn WalkFunc) (err error)

Types

type CompressedFile 

type CompressedFile struct {
	*CompressedFileInfo
	// contains filtered or unexported fields
}

CompressedFile is an opened compressedFile instance.

func (*CompressedFile) Close 

func (f *CompressedFile) Close() error

func (*CompressedFile) Read 

func (f *CompressedFile) Read(p []byte) (n int, err error)

func (*CompressedFile) Seek 

func (f *CompressedFile) Seek(offset int64, whence int) (int64, error)

type CompressedFileInfo 

type CompressedFileInfo struct {
	// contains filtered or unexported fields
}

CompressedFileInfo is a static definition of a gzip compressed file.

func (*CompressedFileInfo) GzipBytes 

func (f *CompressedFileInfo) GzipBytes() []byte

func (*CompressedFileInfo) IsDir 

func (f *CompressedFileInfo) IsDir() bool

func (*CompressedFileInfo) ModTime 

func (f *CompressedFileInfo) ModTime() time.Time

func (*CompressedFileInfo) Mode 

func (f *CompressedFileInfo) Mode() os.FileMode

func (*CompressedFileInfo) Name 

func (f *CompressedFileInfo) Name() string

func (*CompressedFileInfo) Readdir 

func (f *CompressedFileInfo) Readdir(count int) ([]os.FileInfo, error)

func (*CompressedFileInfo) Size 

func (f *CompressedFileInfo) Size() int64

func (*CompressedFileInfo) Stat 

func (f *CompressedFileInfo) Stat() (os.FileInfo, error)

func (*CompressedFileInfo) Sys 

func (f *CompressedFileInfo) Sys() interface{}

type Dir 

type Dir struct {
	*DirInfo
	// contains filtered or unexported fields
}

Dir is an opened dir instance.

func (*Dir) Readdir 

func (d *Dir) Readdir(count int) ([]os.FileInfo, error)

func (*Dir) Seek 

func (d *Dir) Seek(offset int64, whence int) (int64, error)

type DirInfo 

type DirInfo struct {
	// contains filtered or unexported fields
}

DirInfo is a static definition of a directory.

func (*DirInfo) Close 

func (d *DirInfo) Close() error

func (*DirInfo) IsDir 

func (d *DirInfo) IsDir() bool

func (*DirInfo) ModTime 

func (d *DirInfo) ModTime() time.Time

func (*DirInfo) Mode 

func (d *DirInfo) Mode() os.FileMode

func (*DirInfo) Name 

func (d *DirInfo) Name() string

func (*DirInfo) Read 

func (d *DirInfo) Read([]byte) (int, error)

func (*DirInfo) Size 

func (d *DirInfo) Size() int64

func (*DirInfo) Stat 

func (d *DirInfo) Stat() (os.FileInfo, error)

func (*DirInfo) Sys 

func (d *DirInfo) Sys() interface{}

type FS 

type FS struct {
	// contains filtered or unexported fields
}

func NewFS 

func NewFS() *FS

func (*FS) Add 

func (fs *FS) Add(dir, name string, content []byte)

func (*FS) Open 

func (fs *FS) Open(path string) (http.File, error)

func (*FS) Paths 

func (fs *FS) Paths() map[string]interface{}

type FileInfo 

type FileInfo struct {
	Path             string
	Name             string
	ModTime          time.Time
	UncompressedSize int64
}

FileInfo is a definition of a file.

type Options 

type Options struct {
	// Filename of the generated Go code output (including extension).
	// If left empty, it defaults to "{{toLower .VariableName}}_vfsdata.go".
	Filename string

	// PackageName is the name of the package in the generated code.
	// If left empty, it defaults to "main".
	PackageName string

	// BuildTags are the optional build tags in the generated code.
	// The build tags syntax is specified by the go tool.
	BuildTags string

	// VariableName is the name of the http.FileSystem variable in the generated code.
	// If left empty, it defaults to "assets".
	VariableName string

	// VariableComment is the comment of the http.FileSystem variable in the generated code.
	// If left empty, it defaults to "{{.VariableName}} statically implements the virtual filesystem provided to vfsgen.".
	VariableComment string
}

Options for vfsgen code generation.

type WalkFunc 

type WalkFunc func(path string, info fsi.FileInfo, err error) error

Source Files

View all Source files

Directories

Path Synopsis
cmd
vfsgendev
vfsgendev is a convenience tool for using vfsgen in a common development configuration.
 vfsgendev is a convenience tool for using vfsgen in a common development configuration.
Package test contains tests for virtual filesystem implementation generated by vfsgen.
 Package test contains tests for virtual filesystem implementation generated by vfsgen.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.