|
Packit Service |
7770af |
By using custom importers, Sass stylesheets can be implemented in any possible way, such as by being loaded via a remote server. Please note: this feature is experimental and is implemented differently than importers in Ruby Sass. Imports must be relative to the parent import context and therefore we need to pass this information to the importer callback. This is currently done by passing the complete import string/path of the previous import context.
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
## Return Imports
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
You actually have to return a list of imports, since some importers may want to import multiple files from one import statement (ie. a glob/star importer). The memory you pass with source and srcmap is taken over by LibSass and freed automatically when the import is done. You are also allowed to return `0` instead of a list, which will tell LibSass to handle the import by itself (as if no custom importer was in use).
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
```C
|
|
Packit Service |
7770af |
Sass_Import_Entry* rv = sass_make_import_list(1);
|
|
Packit Service |
7770af |
rv[0] = sass_make_import(rel, abs, source, srcmap);
|
|
Packit Service |
7770af |
```
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
Every import will then be included in LibSass. You are allowed to only return a file path without any loaded source. This way you can ie. implement rewrite rules for import paths and leave the loading part for LibSass.
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
Please note that LibSass doesn't use the srcmap parameter yet. It has been added to not deprecate the C-API once support has been implemented. It will be used to re-map the actual sourcemap with the provided ones.
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
### Basic Usage
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
```C
|
|
Packit Service |
7770af |
#include "sass/functions.h"
|
|
Packit Service |
7770af |
```
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
## Sass Importer API
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
```C
|
|
Packit Service |
7770af |
// Forward declaration
|
|
Packit Service |
7770af |
struct Sass_Import;
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
// Forward declaration
|
|
Packit Service |
7770af |
struct Sass_C_Import_Descriptor;
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
// Typedef defining the custom importer callback
|
|
Packit Service |
7770af |
typedef struct Sass_C_Import_Descriptor (*Sass_C_Import_Callback);
|
|
Packit Service |
7770af |
// Typedef defining the importer c function prototype
|
|
Packit Service |
7770af |
typedef Sass_Import_Entry* (*Sass_C_Import_Fn) (const char* url, const char* prev, void* cookie);
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
// Creators for custom importer callback (with some additional pointer)
|
|
Packit Service |
7770af |
// The pointer is mostly used to store the callback into the actual function
|
|
Packit Service |
7770af |
Sass_C_Import_Callback sass_make_importer (Sass_C_Import_Fn, void* cookie);
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
// Getters for import function descriptors
|
|
Packit Service |
7770af |
Sass_C_Import_Fn sass_import_get_function (Sass_C_Import_Callback fn);
|
|
Packit Service |
7770af |
void* sass_import_get_cookie (Sass_C_Import_Callback fn);
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
// Deallocator for associated memory
|
|
Packit Service |
7770af |
void sass_delete_importer (Sass_C_Import_Callback fn);
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
// Creator for sass custom importer return argument list
|
|
Packit Service |
7770af |
Sass_Import_Entry* sass_make_import_list (size_t length);
|
|
Packit Service |
7770af |
// Creator for a single import entry returned by the custom importer inside the list
|
|
Packit Service |
7770af |
Sass_Import_Entry sass_make_import_entry (const char* path, char* source, char* srcmap);
|
|
Packit Service |
7770af |
Sass_Import_Entry sass_make_import (const char* rel, const char* abs, char* source, char* srcmap);
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
// set error message to abort import and to print out a message (path from existing object is used in output)
|
|
Packit Service |
7770af |
Sass_Import_Entry sass_import_set_error(Sass_Import_Entry import, const char* message, size_t line, size_t col);
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
// Setters to insert an entry into the import list (you may also use [] access directly)
|
|
Packit Service |
7770af |
// Since we are dealing with pointers they should have a guaranteed and fixed size
|
|
Packit Service |
7770af |
void sass_import_set_list_entry (Sass_Import_Entry* list, size_t idx, Sass_Import_Entry entry);
|
|
Packit Service |
7770af |
Sass_Import_Entry sass_import_get_list_entry (Sass_Import_Entry* list, size_t idx);
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
// Getters for import entry
|
|
Packit Service |
7770af |
const char* sass_import_get_imp_path (Sass_Import_Entry);
|
|
Packit Service |
7770af |
const char* sass_import_get_abs_path (Sass_Import_Entry);
|
|
Packit Service |
7770af |
const char* sass_import_get_source (Sass_Import_Entry);
|
|
Packit Service |
7770af |
const char* sass_import_get_srcmap (Sass_Import_Entry);
|
|
Packit Service |
7770af |
// Explicit functions to take ownership of these items
|
|
Packit Service |
7770af |
// The property on our struct will be reset to NULL
|
|
Packit Service |
7770af |
char* sass_import_take_source (Sass_Import_Entry);
|
|
Packit Service |
7770af |
char* sass_import_take_srcmap (Sass_Import_Entry);
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
// Getters for import error entries
|
|
Packit Service |
7770af |
size_t sass_import_get_error_line (Sass_Import_Entry);
|
|
Packit Service |
7770af |
size_t sass_import_get_error_column (Sass_Import_Entry);
|
|
Packit Service |
7770af |
const char* sass_import_get_error_message (Sass_Import_Entry);
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
// Deallocator for associated memory (incl. entries)
|
|
Packit Service |
7770af |
void sass_delete_import_list (Sass_Import_Entry*);
|
|
Packit Service |
7770af |
// Just in case we have some stray import structs
|
|
Packit Service |
7770af |
void sass_delete_import (Sass_Import_Entry);
|
|
Packit Service |
7770af |
```
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
### More links
|
|
Packit Service |
7770af |
|
|
Packit Service |
7770af |
- [Sass Importer Example](api-importer-example.md)
|
|
Packit Service |
7770af |
- [Sass Importer Internal](api-importer-internal.md)
|
|
Packit Service |
7770af |
|