API C Documentation

Introduction

Libsass wouldn't be much good without a way to interface with it. These interface documentations describe the various functions and data structures available to implementers. They are split up over three major components, which have all their own source files (plus some common functionality).

• Sass Context - Trigger and handle the main Sass compilation
• Sass Value - Exchange values and its format with libsass
• Sass Function - Get invoked by libsass for function statments
• Sass Importer - Get invoked by libsass for @import statments

Basic usage

First you will need to include the header file!
This will automatically load all other headers too!

#include "sass_context.h"

Deprecated usage

The old API is kept in the source for backward compatibility.
It's deprecated and incompatible with this documentation, use sass_context.h!

// deprecated interface
#include "sass_interface.h"

Basic C Example

#include <stdio.h>
#include "sass_context.h"

int main() {
  puts(libsass_version());
  return 0;
}

gcc -Wall version.c -lsass -o version && ./version

More C Examples

• Sample code for Sass Context
• Sample code for Sass Value
• Sample code for Sass Function
• Sample code for Sass Importer

Compiling your code

The most important is your sass file (or string of sass code). With this, you will want to start a libsass compiler. Here is some pseudocode describing the process. The compiler has two different modes: direct input as a string with Sass_Data_Context or libsass will do file reading for you by using Sass_File_Context. See the code for a list of options available Sass_Options

Building a file compiler

compiler = sass_make_file_context("file.scss")
options = sass_file_context_get_options()
sass_option_set_precision(options, 1)
sass_option_set_source_comments(options, true)

sass_file_context_set_options(compiler, options)
sass_compiler_parse(compiler)
sass_compiler_execute(compiler)

output = sass_context_get_output_string(compiler)
// Retrieve errors during compilation
error_status = sass_context_get_error_status(compiler)
json_error = sass_context_get_error_json(compiler)
// Release memory dedicated to the C compiler
sass_delete_compiler(compiler)

Building a data compiler

compiler = sass_make_data_context("div { a { color: blue; } }")
options = sass_data_context_get_options()
sass_option_set_precision(options, 1)
sass_option_set_source_comments(options, true)

sass_data_context_set_options(compiler, options)
sass_compiler_parse(compiler)
sass_compiler_execute(compiler)

output = sass_context_get_output_string(compiler)
// div a { color: blue; }
// Retrieve errors during compilation
error_status = sass_context_get_error_status(compiler)
json_error = sass_context_get_error_json(compiler)
// Release memory dedicated to the C compiler
sass_delete_compiler(compiler)

Sass Context Internals

Everything is stored in structs:

struct Sass_Options;
struct Sass_Context : Sass_Options;
struct Sass_File_context : Sass_Context;
struct Sass_Data_context : Sass_Context;

This mirrors very well how libsass uses these structures.

• Sass_Options holds everything you feed in before the compilation. It also hosts input_path and output_path options, because they are used to generate/calculate relative links in source-maps. The input_path is shared with Sass_File_Context.
• Sass_Context holds all the data returned by the compilation step.
• Sass_File_Context is a specific implementation that requires no additional fields
• Sass_Data_Context is a specific implementation that adds the input_source field

Structs can be down-casted to access context or options!

Common Pitfalls

input_path

The input_path is part of Sass_Options, but it also is the main option for Sass_File_Context. It is also used to generate relative file links in source-maps. Therefore it is pretty usefull to pass this information if you have a Sass_Data_Context and know the original path.

output_path

Be aware that libsass does not write the output file itself. This option merely exists to give libsass the proper information to generate links in source-maps. The file has to be written to the disk by the binding/implementation. If the output_path is omitted, libsass tries to extrapolate one from the input_path by replacing (or adding) the file ending with .css.

Real-World Implementations

The proof is in the pudding, so we have highlighted a few implementations that should be on par with the latest libsass interface version. Some of them may not have all features implemented!

1. Perl Example
2. Go Example
3. Node Example

ABI forward compatibility

We use a functional API to make dynamic linking more robust and future compatible. The API is not yet 100% stable, so we do not yet guarantee ABI forward compatibility. We will do so, once we increase the shared library version above 1.0.

Internal Structs

• Sass Context Internals
• Sass Value Internals
• Sass Function Internals
• Sass Importer Internals