sassc 1.8.0.pre2 → 1.8.0

data/ext/libsass/docs/api-doc.md

@@ -0,0 +1,160 @@
+## 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](api-context.md) - Trigger and handle the main Sass compilation
+- [Sass Value](api-value.md) - Exchange values and its format with LibSass
+- [Sass Function](api-function.md) - Get invoked by LibSass for function statments
+- [Sass Importer](api-importer.md) - 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!
+
+```C
+#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`!
+
+```C
+// deprecated interface
+#include "sass_interface.h"
+```
+
+## Basic C Example
+
+```C
+#include <stdio.h>
+#include "sass/context.h"
+
+int main() {
+  puts(libsass_VERSION());
+  return 0;
+}
+```
+
+```bash
+gcc -Wall version.c -lsass -o version && ./version
+```
+
+## More C Examples
+
+- [Sample code for Sass Context](api-context-example.md)
+- [Sample code for Sass Value](api-value-example.md)
+- [Sample code for Sass Function](api-function-example.md)
+- [Sample code for Sass Importer](api-importer-example.md)
+
+## 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](https://github.com/sass/libsass/blob/36feef0/include/sass/interface.h#L18)
+
+**Building a file compiler**
+
+    context = sass_make_file_context("file.scss")
+    options = sass_file_context_get_options(context)
+    sass_option_set_precision(options, 1)
+    sass_option_set_source_comments(options, true)
+
+    sass_file_context_set_options(context, options)
+
+    compiler = sass_make_file_compiler(sass_context)
+    sass_compiler_parse(compiler)
+    sass_compiler_execute(compiler)
+
+    output = sass_context_get_output_string(context)
+    // Retrieve errors during compilation
+    error_status = sass_context_get_error_status(context)
+    json_error = sass_context_get_error_json(context)
+    // Release memory dedicated to the C compiler
+    sass_delete_compiler(compiler)
+
+**Building a data compiler**
+
+    context = sass_make_data_context("div { a { color: blue; } }")
+    options = sass_data_context_get_options(context)
+    sass_option_set_precision(options, 1)
+    sass_option_set_source_comments(options, true)
+
+    sass_data_context_set_options(context, options)
+
+    compiler = sass_make_data_compiler(context)
+    sass_compiler_parse(compiler)
+    sass_compiler_execute(compiler)
+
+    output = sass_context_get_output_string(context)
+    // div a { color: blue; }
+    // Retrieve errors during compilation
+    error_status = sass_context_get_error_status(context)
+    json_error = sass_context_get_error_json(context)
+    // Release memory dedicated to the C compiler
+    sass_delete_compiler(compiler)
+
+## Sass Context Internals
+
+Everything is stored in structs:
+
+```C
+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`.
+
+## Error Codes
+
+The `error_code` is integer value which indicates the type of error that occurred inside the LibSass process. Following is the list of error codes along with the short description:
+
+* 1: normal errors like parsing or `eval` errors
+* 2: bad allocation error (memory error)
+* 3: "untranslated" C++ exception (`throw std::exception`)
+* 4: legacy string exceptions ( `throw const char*` or `std::string` )
+* 5: Some other unknown exception
+
+Although for the API consumer, error codes do not offer much value except indicating whether *any* error occurred during the compilation, it helps debugging the LibSass internal code paths.
+
+## 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](https://github.com/sass/perl-libsass/blob/master/lib/CSS/Sass.xs)
+2. [Go Example](http://godoc.org/github.com/wellington/go-libsass#example-Context-Compile)
+3. [Node Example](https://github.com/sass/node-sass/blob/master/src/binding.cpp)
+
+## 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](https://gcc.gnu.org/onlinedocs/libstdc++/manual/abi.html) forward compatibility. We will do so, once we increase the shared library version above 1.0.
+
+## Plugins (experimental)
+
+LibSass can load plugins from directories. Just define `plugin_path` on context options to load all plugins from the given directories. To implement plugins, please consult the [[Wiki-Page for plugins|API-Plugins]].
+
+## Internal Structs
+
+- [Sass Context Internals](api-context-internal.md)
+- [Sass Value Internals](api-value-internal.md)
+- [Sass Function Internals](api-function-internal.md)
+- [Sass Importer Internals](api-importer-internal.md)

data/ext/libsass/docs/api-function-example.md

@@ -0,0 +1,58 @@
+## Example main.c
+
+```C
+#include <stdio.h>
+#include <stdint.h>
+#include "sass/context.h"
+
+union Sass_Value* call_fn_foo(const union Sass_Value* s_args, void* cookie)
+{
+  // we actually abuse the void* to store an "int"
+  return sass_make_number((intptr_t)cookie, "px");
+}
+
+int main( int argc, const char* argv[] )
+{
+
+  // get the input file from first argument or use default
+  const char* input = argc > 1 ? argv[1] : "styles.scss";
+
+  // create the file context and get all related structs
+  struct Sass_File_Context* file_ctx = sass_make_file_context(input);
+  struct Sass_Context* ctx = sass_file_context_get_context(file_ctx);
+  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
+
+  // allocate a custom function caller
+  Sass_C_Function_Callback fn_foo =
+    sass_make_function("foo()", call_fn_foo, (void*)42);
+
+  // create list of all custom functions
+  Sass_C_Function_List fn_list = sass_make_function_list(1);
+  sass_function_set_list_entry(fn_list, 0, fn_foo);
+  sass_option_set_c_functions(ctx_opt, fn_list);
+
+  // context is set up, call the compile step now
+  int status = sass_compile_file_context(file_ctx);
+
+  // print the result or the error to the stdout
+  if (status == 0) puts(sass_context_get_output_string(ctx));
+  else puts(sass_context_get_error_message(ctx));
+
+  // release allocated memory
+  sass_delete_file_context(file_ctx);
+
+  // exit status
+  return status;
+
+}
+```
+
+### Compile main.c
+
+```bash
+gcc -c main.c -o main.o
+gcc -o sample main.o -lsass
+echo "foo { margin: foo(); }" > foo.scss
+./sample foo.scss => "foo { margin: 42px }"
+```
+

data/ext/libsass/docs/api-function-internal.md

@@ -0,0 +1,8 @@
+```C
+// Struct to hold custom function callback
+struct Sass_C_Function_Descriptor {
+  const char*     signature;
+  Sass_C_Function function;
+  void*           cookie;
+};
+```

data/ext/libsass/docs/api-function.md

@@ -0,0 +1,48 @@
+Sass functions are used to define new custom functions callable by Sass code. They are also used to overload debug or error statements. You can also define a fallback function, which is called for every unknown function found in the Sass code. Functions get passed zero or more `Sass_Values` (a `Sass_List` value) and they must also return a `Sass_Value`. Return a `Sass_Error` if you want to signal an error.
+
+## Special signatures
+
+- `*` - Fallback implementation
+- `@warn` - Overload warn statements
+- `@error` - Overload error statements
+- `@debug` - Overload debug statements
+
+Note: The fallback implementation will be given the name of the called function as the first argument, before all the original function arguments. These features are pretty new and should be considered experimental.
+
+### Basic Usage
+
+```C
+#include "sass/functions.h"
+```
+
+## Sass Function API
+
+```C
+// Forward declaration
+struct Sass_C_Function_Descriptor;
+
+// Typedef defining null terminated list of custom callbacks
+typedef struct Sass_C_Function_Descriptor* (*Sass_C_Function_List);
+typedef struct Sass_C_Function_Descriptor (*Sass_C_Function_Callback);
+// Typedef defining custom function prototype and its return value type
+typedef union Sass_Value*(*Sass_C_Function) (const union Sass_Value*, void* cookie);
+
+// Creators for sass function list and function descriptors
+Sass_C_Function_List sass_make_function_list (size_t length);
+Sass_C_Function_Callback sass_make_function (const char* signature, Sass_C_Function fn, void* cookie);
+
+// Setters and getters for callbacks on function lists
+Sass_C_Function_Callback sass_function_get_list_entry(Sass_C_Function_List list, size_t pos);
+void sass_function_set_list_entry(Sass_C_Function_List list, size_t pos, Sass_C_Function_Callback cb);
+
+// Getters for custom function descriptors
+const char* sass_function_get_signature (Sass_C_Function_Callback fn);
+Sass_C_Function sass_function_get_function (Sass_C_Function_Callback fn);
+void* sass_function_get_cookie (Sass_C_Function_Callback fn);
+```
+
+### More links
+
+- [Sass Function Example](api-function-example.md)
+- [Sass Function Internal](api-function-internal.md)
+

data/ext/libsass/docs/api-importer-example.md

@@ -0,0 +1,1345 @@
+## Example importer.c
+
+```C
+#include <stdio.h>
+#include <string.h>
+#include "sass/context.h"
+
+Sass_Import_List sass_importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp)
+{
+  // get the cookie from importer descriptor
+  void* cookie = sass_importer_get_cookie(cb);
+  Sass_Import_List list = sass_make_import_list(2);
+  const char* local = "local { color: green; }";
+  const char* remote = "remote { color: red; }";
+  list[0] = sass_make_import_entry("/tmp/styles.scss", strdup(local), 0);
+  list[1] = sass_make_import_entry("http://www.example.com", strdup(remote), 0);
+  return list;
+}
+
+int main( int argc, const char* argv[] )
+{
+
+  // get the input file from first argument or use default
+  const char* input = argc > 1 ? argv[1] : "styles.scss";
+
+  // create the file context and get all related structs
+  struct Sass_File_Context* file_ctx = sass_make_file_context(input);
+  struct Sass_Context* ctx = sass_file_context_get_context(file_ctx);
+  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
+
+  // allocate custom importer
+  Sass_Importer_Entry c_imp =
+    sass_make_importer(sass_importer, 0, 0);
+  // create list for all custom importers
+  Sass_Importer_List imp_list = sass_make_importer_list(1);
+  // put only the importer on to the list
+  sass_importer_set_list_entry(imp_list, 0, c_imp);
+  // register list on to the context options
+  sass_option_set_c_importers(ctx_opt, imp_list);
+  // context is set up, call the compile step now
+  int status = sass_compile_file_context(file_ctx);
+
+  // print the result or the error to the stdout
+  if (status == 0) puts(sass_context_get_output_string(ctx));
+  else puts(sass_context_get_error_message(ctx));
+
+  // release allocated memory
+  sass_delete_file_context(file_ctx);
+
+  // exit status
+  return status;
+
+}
+```
+
+Compile importer.c
+
+```bash
+gcc -c importer.c -o importer.o
+gcc -o importer importer.o -lsass
+echo "@import 'foobar';" > importer.scss
+./importer importer.scss
+```
+
+## Importer Behavior Examples
+
+```C
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the import request
+  return NULL;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the request
+  // swallows »@import "http://…"« pass-through
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(url, 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // return an error to halt execution
+  Sass_Import_List list = sass_make_import_list(1);
+  const char* message = "some error message";
+  list[0] = sass_make_import_entry(url, 0, 0);
+  sass_import_set_error(list[0], strdup(message), 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass load the file identifed by the importer
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry("/tmp/file.scss", 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(0, 0, 0);
+  return list;
+}
+```
+## Example importer.c
+
+```C
+#include <stdio.h>
+#include <string.h>
+#include "sass/context.h"
+
+Sass_Import_List sass_importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp)
+{
+  // get the cookie from importer descriptor
+  void* cookie = sass_importer_get_cookie(cb);
+  Sass_Import_List list = sass_make_import_list(2);
+  const char* local = "local { color: green; }";
+  const char* remote = "remote { color: red; }";
+  list[0] = sass_make_import_entry("/tmp/styles.scss", strdup(local), 0);
+  list[1] = sass_make_import_entry("http://www.example.com", strdup(remote), 0);
+  return list;
+}
+
+int main( int argc, const char* argv[] )
+{
+
+  // get the input file from first argument or use default
+  const char* input = argc > 1 ? argv[1] : "styles.scss";
+
+  // create the file context and get all related structs
+  struct Sass_File_Context* file_ctx = sass_make_file_context(input);
+  struct Sass_Context* ctx = sass_file_context_get_context(file_ctx);
+  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
+
+  // allocate custom importer
+  Sass_Importer_Entry c_imp =
+    sass_make_importer(sass_importer, 0, 0);
+  // create list for all custom importers
+  Sass_Importer_List imp_list = sass_make_importer_list(1);
+  // put the only importer on to the list
+  sass_importer_set_list_entry(imp_list, 0, c_imp);
+  // register list on to the context options
+  sass_option_set_c_importers(ctx_opt, imp_list);
+  // context is set up, call the compile step now
+  int status = sass_compile_file_context(file_ctx);
+
+  // print the result or the error to the stdout
+  if (status == 0) puts(sass_context_get_output_string(ctx));
+  else puts(sass_context_get_error_message(ctx));
+
+  // release allocated memory
+  sass_delete_file_context(file_ctx);
+
+  // exit status
+  return status;
+
+}
+```
+
+Compile importer.c
+
+```bash
+gcc -c importer.c -o importer.o
+gcc -o importer importer.o -lsass
+echo "@import 'foobar';" > importer.scss
+./importer importer.scss
+```
+
+## Importer Behavior Examples
+
+```C
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the import request
+  return NULL;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the request
+  // swallows »@import "http://…"« pass-through
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(url, 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // return an error to halt execution
+  Sass_Import_List list = sass_make_import_list(1);
+  const char* message = "some error message";
+  list[0] = sass_make_import_entry(url, 0, 0);
+  sass_import_set_error(list[0], strdup(message), 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass load the file identifed by the importer
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry("/tmp/file.scss", 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(0, 0, 0);
+  return list;
+}
+```
+## Example importer.c
+
+```C
+#include <stdio.h>
+#include <string.h>
+#include "sass/context.h"
+
+Sass_Import_List sass_importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp)
+{
+  // get the cookie from importer descriptor
+  void* cookie = sass_importer_get_cookie(cb);
+  Sass_Import_List list = sass_make_import_list(2);
+  const char* local = "local { color: green; }";
+  const char* remote = "remote { color: red; }";
+  list[0] = sass_make_import_entry("/tmp/styles.scss", strdup(local), 0);
+  list[1] = sass_make_import_entry("http://www.example.com", strdup(remote), 0);
+  return list;
+}
+
+int main( int argc, const char* argv[] )
+{
+
+  // get the input file from first argument or use default
+  const char* input = argc > 1 ? argv[1] : "styles.scss";
+
+  // create the file context and get all related structs
+  struct Sass_File_Context* file_ctx = sass_make_file_context(input);
+  struct Sass_Context* ctx = sass_file_context_get_context(file_ctx);
+  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
+
+  // allocate custom importer
+  Sass_Importer_Entry c_imp =
+    sass_make_importer(sass_importer, 0, 0);
+  // create list for all custom importers
+  Sass_Importer_List imp_list = sass_make_importer_list(1);
+  // put the only importer on to the list
+  sass_importer_set_list_entry(imp_list, 0, c_imp);
+  // register list on to the context options
+  sass_option_set_c_importers(ctx_opt, imp_list);
+  // context is set up, call the compile step now
+  int status = sass_compile_file_context(file_ctx);
+
+  // print the result or the error to the stdout
+  if (status == 0) puts(sass_context_get_output_string(ctx));
+  else puts(sass_context_get_error_message(ctx));
+
+  // release allocated memory
+  sass_delete_file_context(file_ctx);
+
+  // exit status
+  return status;
+
+}
+```
+
+Compile importer.c
+
+```bash
+gcc -c importer.c -o importer.o
+gcc -o importer importer.o -lsass
+echo "@import 'foobar';" > importer.scss
+./importer importer.scss
+```
+
+## Importer Behavior Examples
+
+```C
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the import request
+  return NULL;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the request
+  // swallows »@import "http://…"« pass-through
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(url, 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // return an error to halt execution
+  Sass_Import_List list = sass_make_import_list(1);
+  const char* message = "some error message";
+  list[0] = sass_make_import_entry(url, 0, 0);
+  sass_import_set_error(list[0], strdup(message), 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass load the file identifed by the importer
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry("/tmp/file.scss", 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(0, 0, 0);
+  return list;
+}
+```
+## Example importer.c
+
+```C
+#include <stdio.h>
+#include <string.h>
+#include "sass/context.h"
+
+Sass_Import_List sass_importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp)
+{
+  // get the cookie from importer descriptor
+  void* cookie = sass_importer_get_cookie(cb);
+  Sass_Import_List list = sass_make_import_list(2);
+  const char* local = "local { color: green; }";
+  const char* remote = "remote { color: red; }";
+  list[0] = sass_make_import_entry("/tmp/styles.scss", strdup(local), 0);
+  list[1] = sass_make_import_entry("http://www.example.com", strdup(remote), 0);
+  return list;
+}
+
+int main( int argc, const char* argv[] )
+{
+
+  // get the input file from first argument or use default
+  const char* input = argc > 1 ? argv[1] : "styles.scss";
+
+  // create the file context and get all related structs
+  struct Sass_File_Context* file_ctx = sass_make_file_context(input);
+  struct Sass_Context* ctx = sass_file_context_get_context(file_ctx);
+  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
+
+  // allocate custom importer
+  Sass_Importer_Entry c_imp =
+    sass_make_importer(sass_importer, 0, 0);
+  // create list for all custom importers
+  Sass_Importer_List imp_list = sass_make_importer_list(1);
+  // put the only importer on to the list
+  sass_importer_set_list_entry(imp_list, 0, c_imp);
+  // register list on to the context options
+  sass_option_set_c_importers(ctx_opt, imp_list);
+  // context is set up, call the compile step now
+  int status = sass_compile_file_context(file_ctx);
+
+  // print the result or the error to the stdout
+  if (status == 0) puts(sass_context_get_output_string(ctx));
+  else puts(sass_context_get_error_message(ctx));
+
+  // release allocated memory
+  sass_delete_file_context(file_ctx);
+
+  // exit status
+  return status;
+
+}
+```
+
+Compile importer.c
+
+```bash
+gcc -c importer.c -o importer.o
+gcc -o importer importer.o -lsass
+echo "@import 'foobar';" > importer.scss
+./importer importer.scss
+```
+
+## Importer Behavior Examples
+
+```C
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the import request
+  return NULL;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the request
+  // swallows »@import "http://…"« pass-through
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(url, 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // return an error to halt execution
+  Sass_Import_List list = sass_make_import_list(1);
+  const char* message = "some error message";
+  list[0] = sass_make_import_entry(url, 0, 0);
+  sass_import_set_error(list[0], strdup(message), 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass load the file identifed by the importer
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry("/tmp/file.scss", 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(0, 0, 0);
+  return list;
+}
+```
+## Example importer.c
+
+```C
+#include <stdio.h>
+#include <string.h>
+#include "sass/context.h"
+
+Sass_Import_List sass_importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp)
+{
+  // get the cookie from importer descriptor
+  void* cookie = sass_importer_get_cookie(cb);
+  Sass_Import_List list = sass_make_import_list(2);
+  const char* local = "local { color: green; }";
+  const char* remote = "remote { color: red; }";
+  list[0] = sass_make_import_entry("/tmp/styles.scss", strdup(local), 0);
+  list[1] = sass_make_import_entry("http://www.example.com", strdup(remote), 0);
+  return list;
+}
+
+int main( int argc, const char* argv[] )
+{
+
+  // get the input file from first argument or use default
+  const char* input = argc > 1 ? argv[1] : "styles.scss";
+
+  // create the file context and get all related structs
+  struct Sass_File_Context* file_ctx = sass_make_file_context(input);
+  struct Sass_Context* ctx = sass_file_context_get_context(file_ctx);
+  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
+
+  // allocate custom importer
+  Sass_Importer_Entry c_imp =
+    sass_make_importer(sass_importer, 0, 0);
+  // create list for all custom importers
+  Sass_Importer_List imp_list = sass_make_importer_list(1);
+  // put the only importer on to the list
+  sass_importer_set_list_entry(imp_list, 0, c_imp);
+  // register list on to the context options
+  sass_option_set_c_importers(ctx_opt, imp_list);
+  // context is set up, call the compile step now
+  int status = sass_compile_file_context(file_ctx);
+
+  // print the result or the error to the stdout
+  if (status == 0) puts(sass_context_get_output_string(ctx));
+  else puts(sass_context_get_error_message(ctx));
+
+  // release allocated memory
+  sass_delete_file_context(file_ctx);
+
+  // exit status
+  return status;
+
+}
+```
+
+Compile importer.c
+
+```bash
+gcc -c importer.c -o importer.o
+gcc -o importer importer.o -lsass
+echo "@import 'foobar';" > importer.scss
+./importer importer.scss
+```
+
+## Importer Behavior Examples
+
+```C
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the import request
+  return NULL;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the request
+  // swallows »@import "http://…"« pass-through
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(url, 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // return an error to halt execution
+  Sass_Import_List list = sass_make_import_list(1);
+  const char* message = "some error message";
+  list[0] = sass_make_import_entry(url, 0, 0);
+  sass_import_set_error(list[0], strdup(message), 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass load the file identifed by the importer
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry("/tmp/file.scss", 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(0, 0, 0);
+  return list;
+}
+```
+## Example importer.c
+
+```C
+#include <stdio.h>
+#include <string.h>
+#include "sass/context.h"
+
+Sass_Import_List sass_importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp)
+{
+  // get the cookie from importer descriptor
+  void* cookie = sass_importer_get_cookie(cb);
+  Sass_Import_List list = sass_make_import_list(2);
+  const char* local = "local { color: green; }";
+  const char* remote = "remote { color: red; }";
+  list[0] = sass_make_import_entry("/tmp/styles.scss", strdup(local), 0);
+  list[1] = sass_make_import_entry("http://www.example.com", strdup(remote), 0);
+  return list;
+}
+
+int main( int argc, const char* argv[] )
+{
+
+  // get the input file from first argument or use default
+  const char* input = argc > 1 ? argv[1] : "styles.scss";
+
+  // create the file context and get all related structs
+  struct Sass_File_Context* file_ctx = sass_make_file_context(input);
+  struct Sass_Context* ctx = sass_file_context_get_context(file_ctx);
+  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
+
+  // allocate custom importer
+  Sass_Importer_Entry c_imp =
+    sass_make_importer(sass_importer, 0, 0);
+  // create list for all custom importers
+  Sass_Importer_List imp_list = sass_make_importer_list(1);
+  // put the only importer on to the list
+  sass_importer_set_list_entry(imp_list, 0, c_imp);
+  // register list on to the context options
+  sass_option_set_c_importers(ctx_opt, imp_list);
+  // context is set up, call the compile step now
+  int status = sass_compile_file_context(file_ctx);
+
+  // print the result or the error to the stdout
+  if (status == 0) puts(sass_context_get_output_string(ctx));
+  else puts(sass_context_get_error_message(ctx));
+
+  // release allocated memory
+  sass_delete_file_context(file_ctx);
+
+  // exit status
+  return status;
+
+}
+```
+
+Compile importer.c
+
+```bash
+gcc -c importer.c -o importer.o
+gcc -o importer importer.o -lsass
+echo "@import 'foobar';" > importer.scss
+./importer importer.scss
+```
+
+## Importer Behavior Examples
+
+```C
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the import request
+  return NULL;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the request
+  // swallows »@import "http://…"« pass-through
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(url, 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // return an error to halt execution
+  Sass_Import_List list = sass_make_import_list(1);
+  const char* message = "some error message";
+  list[0] = sass_make_import_entry(url, 0, 0);
+  sass_import_set_error(list[0], strdup(message), 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass load the file identifed by the importer
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry("/tmp/file.scss", 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(0, 0, 0);
+  return list;
+}
+```
+## Example importer.c
+
+```C
+#include <stdio.h>
+#include <string.h>
+#include "sass/context.h"
+
+Sass_Import_List sass_importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp)
+{
+  // get the cookie from importer descriptor
+  void* cookie = sass_importer_get_cookie(cb);
+  Sass_Import_List list = sass_make_import_list(2);
+  const char* local = "local { color: green; }";
+  const char* remote = "remote { color: red; }";
+  list[0] = sass_make_import_entry("/tmp/styles.scss", strdup(local), 0);
+  list[1] = sass_make_import_entry("http://www.example.com", strdup(remote), 0);
+  return list;
+}
+
+int main( int argc, const char* argv[] )
+{
+
+  // get the input file from first argument or use default
+  const char* input = argc > 1 ? argv[1] : "styles.scss";
+
+  // create the file context and get all related structs
+  struct Sass_File_Context* file_ctx = sass_make_file_context(input);
+  struct Sass_Context* ctx = sass_file_context_get_context(file_ctx);
+  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
+
+  // allocate custom importer
+  Sass_Importer_Entry c_imp =
+    sass_make_importer(sass_importer, 0, 0);
+  // create list for all custom importers
+  Sass_Importer_List imp_list = sass_make_importer_list(1);
+  // put the only importer on to the list
+  sass_importer_set_list_entry(imp_list, 0, c_imp);
+  // register list on to the context options
+  sass_option_set_c_importers(ctx_opt, imp_list);
+  // context is set up, call the compile step now
+  int status = sass_compile_file_context(file_ctx);
+
+  // print the result or the error to the stdout
+  if (status == 0) puts(sass_context_get_output_string(ctx));
+  else puts(sass_context_get_error_message(ctx));
+
+  // release allocated memory
+  sass_delete_file_context(file_ctx);
+
+  // exit status
+  return status;
+
+}
+```
+
+Compile importer.c
+
+```bash
+gcc -c importer.c -o importer.o
+gcc -o importer importer.o -lsass
+echo "@import 'foobar';" > importer.scss
+./importer importer.scss
+```
+
+## Importer Behavior Examples
+
+```C
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the import request
+  return NULL;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the request
+  // swallows »@import "http://…"« pass-through
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(url, 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // return an error to halt execution
+  Sass_Import_List list = sass_make_import_list(1);
+  const char* message = "some error message";
+  list[0] = sass_make_import_entry(url, 0, 0);
+  sass_import_set_error(list[0], strdup(message), 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass load the file identifed by the importer
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry("/tmp/file.scss", 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(0, 0, 0);
+  return list;
+}
+```
+## Example importer.c
+
+```C
+#include <stdio.h>
+#include <string.h>
+#include "sass/context.h"
+
+Sass_Import_List sass_importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp)
+{
+  // get the cookie from importer descriptor
+  void* cookie = sass_importer_get_cookie(cb);
+  Sass_Import_List list = sass_make_import_list(2);
+  const char* local = "local { color: green; }";
+  const char* remote = "remote { color: red; }";
+  list[0] = sass_make_import_entry("/tmp/styles.scss", strdup(local), 0);
+  list[1] = sass_make_import_entry("http://www.example.com", strdup(remote), 0);
+  return list;
+}
+
+int main( int argc, const char* argv[] )
+{
+
+  // get the input file from first argument or use default
+  const char* input = argc > 1 ? argv[1] : "styles.scss";
+
+  // create the file context and get all related structs
+  struct Sass_File_Context* file_ctx = sass_make_file_context(input);
+  struct Sass_Context* ctx = sass_file_context_get_context(file_ctx);
+  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
+
+  // allocate custom importer
+  Sass_Importer_Entry c_imp =
+    sass_make_importer(sass_importer, 0, 0);
+  // create list for all custom importers
+  Sass_Importer_List imp_list = sass_make_importer_list(1);
+  // put the only importer on to the list
+  sass_importer_set_list_entry(imp_list, 0, c_imp);
+  // register list on to the context options
+  sass_option_set_c_importers(ctx_opt, imp_list);
+  // context is set up, call the compile step now
+  int status = sass_compile_file_context(file_ctx);
+
+  // print the result or the error to the stdout
+  if (status == 0) puts(sass_context_get_output_string(ctx));
+  else puts(sass_context_get_error_message(ctx));
+
+  // release allocated memory
+  sass_delete_file_context(file_ctx);
+
+  // exit status
+  return status;
+
+}
+```
+
+Compile importer.c
+
+```bash
+gcc -c importer.c -o importer.o
+gcc -o importer importer.o -lsass
+echo "@import 'foobar';" > importer.scss
+./importer importer.scss
+```
+
+## Importer Behavior Examples
+
+```C
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the import request
+  return NULL;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the request
+  // swallows »@import "http://…"« pass-through
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(url, 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // return an error to halt execution
+  Sass_Import_List list = sass_make_import_list(1);
+  const char* message = "some error message";
+  list[0] = sass_make_import_entry(url, 0, 0);
+  sass_import_set_error(list[0], strdup(message), 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass load the file identifed by the importer
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry("/tmp/file.scss", 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(0, 0, 0);
+  return list;
+}
+```
+## Example importer.c
+
+```C
+#include <stdio.h>
+#include <string.h>
+#include "sass/context.h"
+
+Sass_Import_List sass_importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp)
+{
+  // get the cookie from importer descriptor
+  void* cookie = sass_importer_get_cookie(cb);
+  Sass_Import_List list = sass_make_import_list(2);
+  const char* local = "local { color: green; }";
+  const char* remote = "remote { color: red; }";
+  list[0] = sass_make_import_entry("/tmp/styles.scss", strdup(local), 0);
+  list[1] = sass_make_import_entry("http://www.example.com", strdup(remote), 0);
+  return list;
+}
+
+int main( int argc, const char* argv[] )
+{
+
+  // get the input file from first argument or use default
+  const char* input = argc > 1 ? argv[1] : "styles.scss";
+
+  // create the file context and get all related structs
+  struct Sass_File_Context* file_ctx = sass_make_file_context(input);
+  struct Sass_Context* ctx = sass_file_context_get_context(file_ctx);
+  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
+
+  // allocate custom importer
+  Sass_Importer_Entry c_imp =
+    sass_make_importer(sass_importer, 0, 0);
+  // create list for all custom importers
+  Sass_Importer_List imp_list = sass_make_importer_list(1);
+  // put the only importer on to the list
+  sass_importer_set_list_entry(imp_list, 0, c_imp);
+  // register list on to the context options
+  sass_option_set_c_importers(ctx_opt, imp_list);
+  // context is set up, call the compile step now
+  int status = sass_compile_file_context(file_ctx);
+
+  // print the result or the error to the stdout
+  if (status == 0) puts(sass_context_get_output_string(ctx));
+  else puts(sass_context_get_error_message(ctx));
+
+  // release allocated memory
+  sass_delete_file_context(file_ctx);
+
+  // exit status
+  return status;
+
+}
+```
+
+Compile importer.c
+
+```bash
+gcc -c importer.c -o importer.o
+gcc -o importer importer.o -lsass
+echo "@import 'foobar';" > importer.scss
+./importer importer.scss
+```
+
+## Importer Behavior Examples
+
+```C
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the import request
+  return NULL;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the request
+  // swallows »@import "http://…"« pass-through
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(url, 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // return an error to halt execution
+  Sass_Import_List list = sass_make_import_list(1);
+  const char* message = "some error message";
+  list[0] = sass_make_import_entry(url, 0, 0);
+  sass_import_set_error(list[0], strdup(message), 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass load the file identifed by the importer
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry("/tmp/file.scss", 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(0, 0, 0);
+  return list;
+}
+```
+## Example importer.c
+
+```C
+#include <stdio.h>
+#include <string.h>
+#include "sass/context.h"
+
+Sass_Import_List sass_importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp)
+{
+  // get the cookie from importer descriptor
+  void* cookie = sass_importer_get_cookie(cb);
+  Sass_Import_List list = sass_make_import_list(2);
+  const char* local = "local { color: green; }";
+  const char* remote = "remote { color: red; }";
+  list[0] = sass_make_import_entry("/tmp/styles.scss", strdup(local), 0);
+  list[1] = sass_make_import_entry("http://www.example.com", strdup(remote), 0);
+  return list;
+}
+
+int main( int argc, const char* argv[] )
+{
+
+  // get the input file from first argument or use default
+  const char* input = argc > 1 ? argv[1] : "styles.scss";
+
+  // create the file context and get all related structs
+  struct Sass_File_Context* file_ctx = sass_make_file_context(input);
+  struct Sass_Context* ctx = sass_file_context_get_context(file_ctx);
+  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
+
+  // allocate custom importer
+  Sass_Importer_Entry c_imp =
+    sass_make_importer(sass_importer, 0, 0);
+  // create list for all custom importers
+  Sass_Importer_List imp_list = sass_make_importer_list(1);
+  // put the only importer on to the list
+  sass_importer_set_list_entry(imp_list, 0, c_imp);
+  // register list on to the context options
+  sass_option_set_c_importers(ctx_opt, imp_list);
+  // context is set up, call the compile step now
+  int status = sass_compile_file_context(file_ctx);
+
+  // print the result or the error to the stdout
+  if (status == 0) puts(sass_context_get_output_string(ctx));
+  else puts(sass_context_get_error_message(ctx));
+
+  // release allocated memory
+  sass_delete_file_context(file_ctx);
+
+  // exit status
+  return status;
+
+}
+```
+
+Compile importer.c
+
+```bash
+gcc -c importer.c -o importer.o
+gcc -o importer importer.o -lsass
+echo "@import 'foobar';" > importer.scss
+./importer importer.scss
+```
+
+## Importer Behavior Examples
+
+```C
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the import request
+  return NULL;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the request
+  // swallows »@import "http://…"« pass-through
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(url, 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // return an error to halt execution
+  Sass_Import_List list = sass_make_import_list(1);
+  const char* message = "some error message";
+  list[0] = sass_make_import_entry(url, 0, 0);
+  sass_import_set_error(list[0], strdup(message), 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass load the file identifed by the importer
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry("/tmp/file.scss", 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(0, 0, 0);
+  return list;
+}
+```
+## Example importer.c
+
+```C
+#include <stdio.h>
+#include <string.h>
+#include "sass/context.h"
+
+Sass_Import_List sass_importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp)
+{
+  // get the cookie from importer descriptor
+  void* cookie = sass_importer_get_cookie(cb);
+  Sass_Import_List list = sass_make_import_list(2);
+  const char* local = "local { color: green; }";
+  const char* remote = "remote { color: red; }";
+  list[0] = sass_make_import_entry("/tmp/styles.scss", strdup(local), 0);
+  list[1] = sass_make_import_entry("http://www.example.com", strdup(remote), 0);
+  return list;
+}
+
+int main( int argc, const char* argv[] )
+{
+
+  // get the input file from first argument or use default
+  const char* input = argc > 1 ? argv[1] : "styles.scss";
+
+  // create the file context and get all related structs
+  struct Sass_File_Context* file_ctx = sass_make_file_context(input);
+  struct Sass_Context* ctx = sass_file_context_get_context(file_ctx);
+  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
+
+  // allocate custom importer
+  Sass_Importer_Entry c_imp =
+    sass_make_importer(sass_importer, 0, 0);
+  // create list for all custom importers
+  Sass_Importer_List imp_list = sass_make_importer_list(1);
+  // put the only importer on to the list
+  sass_importer_set_list_entry(imp_list, 0, c_imp);
+  // register list on to the context options
+  sass_option_set_c_importers(ctx_opt, imp_list);
+  // context is set up, call the compile step now
+  int status = sass_compile_file_context(file_ctx);
+
+  // print the result or the error to the stdout
+  if (status == 0) puts(sass_context_get_output_string(ctx));
+  else puts(sass_context_get_error_message(ctx));
+
+  // release allocated memory
+  sass_delete_file_context(file_ctx);
+
+  // exit status
+  return status;
+
+}
+```
+
+Compile importer.c
+
+```bash
+gcc -c importer.c -o importer.o
+gcc -o importer importer.o -lsass
+echo "@import 'foobar';" > importer.scss
+./importer importer.scss
+```
+
+## Importer Behavior Examples
+
+```C
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the import request
+  return NULL;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the request
+  // swallows »@import "http://…"« pass-through
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(url, 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // return an error to halt execution
+  Sass_Import_List list = sass_make_import_list(1);
+  const char* message = "some error message";
+  list[0] = sass_make_import_entry(url, 0, 0);
+  sass_import_set_error(list[0], strdup(message), 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass load the file identifed by the importer
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry("/tmp/file.scss", 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(0, 0, 0);
+  return list;
+}
+```
+## Example importer.c
+
+```C
+#include <stdio.h>
+#include <string.h>
+#include "sass/context.h"
+
+Sass_Import_List sass_importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp)
+{
+  // get the cookie from importer descriptor
+  void* cookie = sass_importer_get_cookie(cb);
+  Sass_Import_List list = sass_make_import_list(2);
+  const char* local = "local { color: green; }";
+  const char* remote = "remote { color: red; }";
+  list[0] = sass_make_import_entry("/tmp/styles.scss", strdup(local), 0);
+  list[1] = sass_make_import_entry("http://www.example.com", strdup(remote), 0);
+  return list;
+}
+
+int main( int argc, const char* argv[] )
+{
+
+  // get the input file from first argument or use default
+  const char* input = argc > 1 ? argv[1] : "styles.scss";
+
+  // create the file context and get all related structs
+  struct Sass_File_Context* file_ctx = sass_make_file_context(input);
+  struct Sass_Context* ctx = sass_file_context_get_context(file_ctx);
+  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
+
+  // allocate custom importer
+  Sass_Importer_Entry c_imp =
+    sass_make_importer(sass_importer, 0, 0);
+  // create list for all custom importers
+  Sass_Importer_List imp_list = sass_make_importer_list(1);
+  // put the only importer on to the list
+  sass_importer_set_list_entry(imp_list, 0, c_imp);
+  // register list on to the context options
+  sass_option_set_c_importers(ctx_opt, imp_list);
+  // context is set up, call the compile step now
+  int status = sass_compile_file_context(file_ctx);
+
+  // print the result or the error to the stdout
+  if (status == 0) puts(sass_context_get_output_string(ctx));
+  else puts(sass_context_get_error_message(ctx));
+
+  // release allocated memory
+  sass_delete_file_context(file_ctx);
+
+  // exit status
+  return status;
+
+}
+```
+
+Compile importer.c
+
+```bash
+gcc -c importer.c -o importer.o
+gcc -o importer importer.o -lsass
+echo "@import 'foobar';" > importer.scss
+./importer importer.scss
+```
+
+## Importer Behavior Examples
+
+```C
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the import request
+  return NULL;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass handle the request
+  // swallows »@import "http://…"« pass-through
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(url, 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // return an error to halt execution
+  Sass_Import_List list = sass_make_import_list(1);
+  const char* message = "some error message";
+  list[0] = sass_make_import_entry(url, 0, 0);
+  sass_import_set_error(list[0], strdup(message), 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // let LibSass load the file identifed by the importer
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry("/tmp/file.scss", 0, 0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(0);
+  return list;
+}
+
+Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_Compiler* comp) {
+  // completely hide the import
+  // (arguably a bug)
+  Sass_Import_List list = sass_make_import_list(1);
+  list[0] = sass_make_import_entry(0, 0, 0);
+  return list;
+}
+```
+