godartsass

README

This is a Go API backed by the native Dart Sass Embedded executable.

The primary motivation for this project is to provide SCSS support to Hugo. I welcome PRs with bug fixes. I will also consider adding functionality, but please raise an issue discussing it first.

For LibSass bindings in Go, see GoLibSass.

The benchmark below compares GoLibSass with this library. This is almost twice as fast when running single-threaded, but slower when running with multiple Goroutines. We're communicating with the compiler process via stdin/stdout, which becomes the serialized bottle neck here. That may be possible to improve, but for most practical applications (including Hugo), this should not matter.

Transpile/SCSS-16              770µs ± 0%     467µs ± 1%   -39.36%  (p=0.029 n=4+4)
Transpile/SCSS_Parallel-16    92.2µs ± 2%   362.5µs ± 1%  +293.39%  (p=0.029 n=4+4)

name                        old alloc/op   new alloc/op   delta
Transpile/SCSS-16               192B ± 0%     1268B ± 0%  +560.42%  (p=0.029 n=4+4)
Transpile/SCSS_Parallel-16      192B ± 0%     1272B ± 0%  +562.37%  (p=0.029 n=4+4)

name                        old allocs/op  new allocs/op  delta
Transpile/SCSS-16               2.00 ± 0%     19.00 ± 0%  +850.00%  (p=0.029 n=4+4)
Transpile/SCSS_Parallel-16      2.00 ± 0%     19.00 ± 0%  +850.00%  (p=0.029 n=4+4)

Documentation

Overview

Package godartsass provides a Go API for the Dass Sass Embedded protocol.

Index

• Constants
• Variables
• type Args
• type ImportResolver
• type Options
• type OutputStyle
  • func ParseOutputStyle(s string) OutputStyle
• type Result
• type SassError
  • func (e SassError) Error() string
• type SourceSyntax
  • func ParseSourceSyntax(s string) SourceSyntax
• type Transpiler
  • func Start(opts Options) (*Transpiler, error)
  • func (t *Transpiler) Close() error
  • func (t *Transpiler) Execute(args Args) (Result, error)

Constants

const (
	OutputStyleNested     OutputStyle = "NESTED"
	OutputStyleExpanded   OutputStyle = "EXPANDED"
	OutputStyleCompact    OutputStyle = "COMPACT"
	OutputStyleCompressed OutputStyle = "COMPRESSED"

	SourceSyntaxSCSS SourceSyntax = "SCSS"
	SourceSyntaxSASS SourceSyntax = "INDENTED"
	SourceSyntaxCSS  SourceSyntax = "CSS"
)

Variables

var ErrShutdown = errors.New("connection is shut down")

ErrShutdown will be returned from Execute if the transpiler is or is about to be shut down.

Types

type Args

type Args struct {
	// The input source.
	Source string

	// The URL of the Source.
	// Leave empty if it's unknown.
	// Must include a scheme, e.g. 'file:///myproject/main.scss'
	// See https://en.wikipedia.org/wiki/File_URI_scheme
	//
	// Note: There is an open issue for this value when combined with custom
	// importers, see https://github.com/sass/dart-sass-embedded/issues/24
	URL string

	// Defaults is SCSS.
	SourceSyntax SourceSyntax

	// Default is NESTED.
	OutputStyle OutputStyle

	// If enabled, a sourcemap will be generated and returned in Result.
	EnableSourceMap bool

	// Custom resolver to use to resolve imports.
	// If set, this will be the first in the resolver chain.
	ImportResolver ImportResolver

	// Additional file paths to uses to resolve imports.
	IncludePaths []string
	// contains filtered or unexported fields
}

Args holds the arguments to Execute.

type ImportResolver

type ImportResolver interface {
	CanonicalizeURL(url string) string
	Load(canonicalizedURL string) string
}

ImportResolver allows custom import resolution.

CanonicalizeURL should create a canonical version of the given URL if it's able to resolve it, else return an empty string.

A canonicalized URL should include a scheme, e.g. 'file:///foo/bar.scss', if applicable, see:

https://en.wikipedia.org/wiki/File_URI_scheme

Importers must ensure that the same canonical URL always refers to the same stylesheet.

Load loads the canonicalized URL's content.

type Options

type Options struct {
	// The path to the Dart Sass wrapper binary, an absolute filename
	// if not in $PATH.
	// If this is not set, we will try 'dart-sass-embedded'
	// (or 'dart-sass-embedded.bat' on Windows) in the OS $PATH.
	// There may be several ways to install this, one would be to
	// download it from here: https://github.com/sass/dart-sass-embedded/releases
	DartSassEmbeddedFilename string
}

Options configures a Transpiler.

type OutputStyle

type OutputStyle string

func ParseOutputStyle

func ParseOutputStyle(s string) OutputStyle

ParseOutputStyle will convert s into OutputStyle. Case insensitive, returns OutputStyleNested for unknown value.

type Result

type Result struct {
	CSS       string
	SourceMap string
}

Result holds the result returned from Execute.

type SassError

type SassError struct {
	Message string `json:"message"`
	Span    struct {
		Text  string `json:"text"`
		Start struct {
			Offset int `json:"offset"`
			Column int `json:"column"`
		} `json:"start"`
		End struct {
			Offset int `json:"offset"`
			Column int `json:"column"`
		} `json:"end"`
		Url     string `json:"url"`
		Context string `json:"context"`
	} `json:"span"`
}

SassError is the error returned from Execute on compile errors.

func (SassError) Error

func (e SassError) Error() string

type SourceSyntax

type SourceSyntax string

func ParseSourceSyntax

func ParseSourceSyntax(s string) SourceSyntax

ParseSourceSyntax will convert s into SourceSyntax. Case insensitive, returns SourceSyntaxSCSS for unknown value.

type Transpiler

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

Transpiler controls transpiling of SCSS into CSS.

func Start

func Start(opts Options) (*Transpiler, error)

Start creates an starts a new SCSS transpiler that communicates with the Dass Sass Embedded protocol via Stdin and Stdout.

Closing the transpiler will shut down the process.

Note that the Transpiler is thread safe, and the recommended way of using this is to create one and use that for all the SCSS processing needed.

func (*Transpiler) Close

func (t *Transpiler) Close() error

Close closes the stream to the embedded Dart Sass Protocol, shutting it down. If it is already shutting down, ErrShutdown is returned.

func (*Transpiler) Execute

func (t *Transpiler) Execute(args Args) (Result, error)

Execute transpiles the string Source given in Args into CSS. If Dart Sass resturns a "compile failure", the error returned will be of type SassError.