godartsass

package module
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Jun 9, 2023 License: MIT Imports: 19 Imported by: 22

README

Tests on Linux, MacOS and Windows Go Report Card codecov GoDoc

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.

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

Index

Constants

This section is empty.

Variables

View Source
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

This section is empty.

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 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
	// contains filtered or unexported fields
}

Args holds the arguments to Execute.

type DartSassVersion added in v0.16.0

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 added in v0.16.0

func Version(dartSassEmbeddedFilename string) (DartSassVersion, error)

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

type Import added in v1.1.0

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 added in v0.13.0

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

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

type LogEventType added in v0.13.0

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

	// 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)
}

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 added in v1.0.0

func (t *Transpiler) IsShutDown() bool

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

Directories

Path Synopsis
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL