godartsass

README

This is a Go API backed by the native Dart Sass executable running with sass --embedded.

Note: The v2.x.x of this project targets the v2 of the Dart Sass Embedded protocol with the sass exexutable in releases that can be downloaeded here. For v1 you need to import github.com/bep/godartsass and not github.com/bep/godartsass/v2.

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.

Documentation

Overview

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

Use the Start function to create and start a new thread safe transpiler. Close it when done.

Index

• Variables
• func TestingApplyArgsSettings(args *Args, shouldPanicWhen godartsasstesting.PanicWhen)
• type Args
• type DartSassVersion
  • func Version(dartSassEmbeddedFilename string) (DartSassVersion, error)
• type Import
• type ImportResolver
• type LogEvent
• type LogEventType
• 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)
  • func (t *Transpiler) IsShutDown() bool

Variables

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

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

Functions

func TestingApplyArgsSettings

func TestingApplyArgsSettings(args *Args, shouldPanicWhen godartsasstesting.PanicWhen)

Should only be used in tests.

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/issues/24
	URL string

	// Defaults is SCSS.
	SourceSyntax SourceSyntax

	// Default is EXPANDED.
	OutputStyle OutputStyle

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

	// If enabled, sources will be embedded in the generated source map.
	SourceMapIncludeSources 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

	// Deprecation IDs to silence, e.g. "import".
	SilenceDeprecations []string
	// contains filtered or unexported fields
}

Args holds the arguments to Execute.

type DartSassVersion

type DartSassVersion struct {
	ProtocolVersion       string `json:"protocolVersion"`
	CompilerVersion       string `json:"compilerVersion"`
	ImplementationVersion string `json:"implementationVersion"`
	ImplementationName    string `json:"implementationName"`
	ID                    int    `json:"id"`
}

func Version

func Version(dartSassEmbeddedFilename string) (DartSassVersion, error)

Version returns version information about the Dart Sass frameworks used in dartSassEmbeddedFilename.

type Import

type Import struct {
	// The content of the imported file.
	Content string

	// The syntax of the imported file.
	SourceSyntax SourceSyntax
}

type ImportResolver

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

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 LogEvent

type LogEvent struct {
	// Type is the type of log event.
	Type LogEventType

	// DeprecationType is set if Type is LogEventTypeDeprecated.
	DeprecationType string

	// Message on the form url:line:col message.
	Message string
}

type LogEventType

type LogEventType int

LogEvent is a type of log event from Dart Sass.

const (
	// Usually triggered by the @warn directive.
	LogEventTypeWarning LogEventType = iota

	// Events trigered for usage of deprecated Sass features.
	LogEventTypeDeprecated

	// Triggered by the @debug directive.
	LogEventTypeDebug
)

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'
	// (or 'dart-sass.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/releases
	DartSassEmbeddedFilename string

	// Timeout is the duration allowed for dart sass to transpile.
	// This was added for the beta6 version of Dart Sass Protocol,
	// as running this code against the beta5 binary would hang
	// on Execute.
	Timeout time.Duration

	// LogEventHandler will, if set, receive log events from Dart Sass,
	// e.g. @debug and @warn log statements.
	LogEventHandler func(LogEvent)

	// If not set, will default to os.Stderr.
	Stderr io.Writer
}

Options configures a Transpiler.

type OutputStyle

type OutputStyle string

OutputStyle defines the style of the generated CSS.

const (
	// Expanded (default) output.
	// Note that LibSASS and Ruby SASS have more output styles, and their
	// default is NESTED.
	OutputStyleExpanded OutputStyle = "EXPANDED"

	// Compressed/minified output.
	OutputStyleCompressed OutputStyle = "COMPRESSED"
)

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

SourceSyntax defines the syntax of the source passed in Execute.

const (
	// SCSS style source syntax (default).
	SourceSyntaxSCSS SourceSyntax = "SCSS"

	// Indented or SASS style source syntax.
	SourceSyntaxSASS SourceSyntax = "INDENTED"

	// Regular CSS source syntax.
	SourceSyntaxCSS SourceSyntax = "CSS"
)

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 and 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.

func (*Transpiler) IsShutDown

func (t *Transpiler) IsShutDown() bool

IsShutDown checks if all pending calls have been shut down. Used in tests.