combine

README

Combine

Package combine provides interface to create assets with multiple source of contents (bytes, string, file path or URL). It combines and minifies them on the fly on the first demand on the dedicated file server.

Installation

$ go get github.com/rvflash/combine
$ cd $GOPATH/src/github.com/rvflash/combine
$ dep ensure

Usage

See example for real usage. Errors are ignored for the demo.

import "github.com/rvflash/combine"
// ...
// Creates a box with the path to the local file resources
// and the path to store combined / minified assets.
static := combine.NewBox("./src", "./combine")
// Deletes all files cache on exit. 
defer func() { _ = static.Close() }()
// ...
// Creates a asset.
css := static.NewCSS()
_ = css.AddURL("https://raw.githubusercontent.com/twbs/bootstrap/v4-dev/dist/css/bootstrap-reboot.css")
_ = css.AddString(".blue{ color: #4286f4; }")
_ = css.AddFile("local/file/is_src_dir.css")
// Uses it in a HTML template by retrieving its path or tag.
// By default, a build version will also added.
tag := css.Tag("/static/")
// ...
// Serves combined and minifed resousrces
http.Handle("/static/", http.FileServer(static))
http.ListenAndServe(":8080", nil)

Documentation

Overview

Package combine provides interface to create assets with multiple source of contents and to combine it on the fly. It also provides methods to launch a file server to serve them.

Index

• Constants
• Variables
• type Aggregator
• type Box
  • func NewBox(src, dst Dir) *Box
  • func (b *Box) Close() (err error)
  • func (b *Box) Delete(key fmt.Stringer)
  • func (b *Box) Load(key fmt.Stringer) (value *Static, ok bool)
  • func (b *Box) LoadOrStore(key fmt.Stringer, value *Static) (actual *Static, loaded bool)
  • func (b *Box) NewCSS() File
  • func (b *Box) NewJS() File
  • func (b *Box) Open(name string) (http.File, error)
  • func (b *Box) Store(key fmt.Stringer, value *Static)
  • func (b *Box) ToAsset(mediaType, hash string) (File, error)
  • func (b *Box) UseBuildVersion(value string) *Box
  • func (b *Box) UseHTTPClient(client HTTPGetter) *Box
• type Combiner
• type Dir
  • func (d Dir) String() string
• type File
• type HTTPGetter
• type Static
• type StringCombiner
• type Tagger

Examples

• Box.Open

Constants

const (
	// CSS is the MIME type for CSS content.
	CSS = "text/css"
	// CSS is the MIME type for JavaScript content.
	JavaScript = "text/javascript"
)

List of available MIME types

Variables

var (
	// ErrExist is returned when asset already exists.
	ErrExist = errors.New("asset already exists")
	// ErrUnexpectedEOF means that the asset is empty.
	ErrUnexpectedEOF = errors.New("unexpected EOF")
	// ErrMime is returned ii the mime type is not managed.
	ErrMime = errors.New("unknown mime type")
	// ErrNotFound is returned ii the asset is not found.
	ErrNotFound = errors.New("not found")
)

List of errors

Types

type Aggregator

type Aggregator interface {
	// Add adds a slice of byte as part of the asset.
	// An error is returned if we fails to deal with it.
	Add(buf ...[]byte) error
	// AddFile stores the file names as future part of the asset.
	// Only checks stats to verify if it exists.
	// If not, an error is returned.
	AddFile(name ...string) error
	// AddString adds each string as part of the asset.
	// An error is returned if we fails to deal with it.
	AddString(str ...string) error
	// AddURL stores the file URLs as future part of the asset.
	// An error is returned is one URL is invalid.
	AddURL(url ...string) error
}

Aggregator is the interface implemented by asset to add content inside.

type Box

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

Box represent a virtual folder to store or retrieve combined and minified assets.

func NewBox

func NewBox(src, dst Dir) *Box

NewBox returns a new instance of Box.

func (*Box) Close

func (b *Box) Close() (err error)

Close cleans it workspace by removing cache files. It implements the io.Closer interface.

func (*Box) Delete

func (b *Box) Delete(key fmt.Stringer)

Delete deletes the value for a key.

func (*Box) Load

func (b *Box) Load(key fmt.Stringer) (value *Static, ok bool)

Load returns the value stored in the map for a key, or nil if no value is present. The ok result indicates whether value was found in the map.

func (*Box) LoadOrStore

func (b *Box) LoadOrStore(key fmt.Stringer, value *Static) (actual *Static, loaded bool)

LoadOrStore returns the existing value for the key if present. Otherwise, it stores and returns the given value. The loaded result is true if the value was loaded, false if stored.

func (*Box) NewCSS

func (b *Box) NewCSS() File

NewCSS returns a new resource CSS.

func (*Box) NewJS

func (b *Box) NewJS() File

NewCSS returns a new resource JS.

func (*Box) Open

func (b *Box) Open(name string) (http.File, error)

Open implements the http.FileSystem.

Example

package main

import (
	"net/http"

	"github.com/rvflash/combine"
)

func main() {
	box := combine.NewBox("./example/src", "")
	defer func() { _ = box.Close() }()
	/// ...
	http.Handle("/", http.FileServer(box))
	http.ListenAndServe(":8080", nil)
}

func (*Box) Store

func (b *Box) Store(key fmt.Stringer, value *Static)

Store sets the path for the given identifier.

func (*Box) ToAsset

func (b *Box) ToAsset(mediaType, hash string) (File, error)

ToAsset transforms a hash with its media type to a CSS or JS asset. If it fails, an error is returned instead.

func (*Box) UseBuildVersion

func (b *Box) UseBuildVersion(value string) *Box

UseBuildVersion overwrites the default buidd version by the given value. This build ID prevents unwanted browser caching after changing of the asset.

func (*Box) UseHTTPClient

func (b *Box) UseHTTPClient(client HTTPGetter) *Box

UseHTTPClient allows to use your own HTTP client or proxy.

type Combiner

type Combiner interface {
	// Combine tries to write the result of all combined and minified
	// parts of the content of the asset to w or returns an error.
	Combine(w io.Writer) error
}

Combiner must be implement to combine minified contents.

type Dir

type Dir string

Dir defines the current workspace. An empty Dir is treated as ".".

func (Dir) String

func (d Dir) String() string

String implements the fmt.Stringer interface.

type File

type File interface {
	Aggregator
	Tagger
	StringCombiner
}

File ...

type HTTPGetter

type HTTPGetter interface {
	Get(url string) (*http.Response, error)
}

HTTPGetter represents the mean to get data from HTTP.

type Static

type Static struct {
	Link string
	sync.WaitGroup
}

Static represents the minified and combined version of the asset.

type StringCombiner

type StringCombiner interface {
	fmt.Stringer
	Combiner
}

StringCombiner ...

type Tagger

type Tagger interface {
	// URL returns the relative path of the asset.
	Path(root Dir) string
	// Tag returns a link as a HTML tag to the asset.
	Tag(root Dir) string
}

Tagger must be implemented by an asset to be used in HTML5.