node-sass-filefunctions - Filename and path handling for SASS/SCSS

Ever wanted to automatically generate styles based on available assets? This package provides the facilities for identifying the assets in your work directory and manipulating their filenames in the ways you will need to produce viable CSS class descriptions for them.

Usage

These functions are implemented as a plugin to node-sass. To integrate them, you need to provide the functions option to the node-sass processing function, for example:

const sass = require ('node-sass');
const sassFileFunctions = require ('node-sass-filefunctions');
...
var result = sass.renderSync ({
    data: "... SASS or SCSS content goes here ...",
    functions: sassFileFunctions.nodeSassFileFunctions ()
});

In case you are already using some custom functions for node-sass, the retrieval function can accept an object containing a collection of functions that are used to extend the object it returns:

var myOtherFunctions = { "frobnicate($foo)": do_sass_frobinication };

var result = sass.renderSync ({
    data: "... SASS or SCSS content goes here ...",
    functions: sassFileFunctions.nodeSassFileFunctions (myOtherFunctions)
});

The functions

The functions provided are:

glob($pattern, $dir: null)

Expand wildcards (e.g. "*" and "?" for matching unknown characters, "**" for matching parent directories, "[abc]" for character classes, and "{a,b,c}" for alternation) into matching filenames. The path separator is always returned as "/". If $dir is specified, it is the directory to run the expansion in (the process current working directory is the default).

Returns a list of strings, one for each match. Uses the glob package; more documentation on the behaviour of the patterns is available there.

For example:

@each $file in glob('../assets/*.png') {
    .bg-#{basename($file, ".png")} { background-image: url('#{$file}'); }
}

basename($path, $ext: null)

Returns the basename of the path (i.e., the filename part without directories). If the optional parameter "$ext" is specified, it contains an extension that is stripped out of the name if present.

For example, basename("../assets/checkerboard.png", ".png") gives the result checkerboard.

dirname($path)

Similar to basename, but returns the directories rather than the filename.

For example, dirname("../assets/checkerboard.png") gives the result ../assets.

extname($path)

Returns only the extension part (if any) of a path name, including the leading dot. If the path name has no extension, returns the empty string.

For example, extname("../assets/checkerboard.png") gives the result .png.

joinPath($path1, $path2)

Joins two paths together. In case the resulting path contains backslash characters (e.g. because the operation is performed under Windows), these are converted to forward slashes (as they are most likely to be used in a URL, and this is the form of separator expected in this case).

For example, joinPath ("../assets", "lo-res/checkerboard.png") gives the result ../assets/lo-res/checkerboard.png.

resolvePath($path1, $path2)

Merges two paths together and returns the canonical path name of the combined path. Note that if neither path is absolute, the first will be resolved as relative to the current working directory. In most cases, this is not useful, so you should generally ensure that $path1 is absolute. As for joinPath, path separators are returned as forward slashes, even on systems where backslash is the default.

For example, resolvePath ("/assets/lo-res", "../checkerboard.png") gives the result /assets/checkerboard.png.