Blame docs/api-doc.md

Packit Service 7770af
## Introduction
Packit Service 7770af
Packit Service 7770af
LibSass wouldn't be much good without a way to interface with it. These
Packit Service 7770af
interface documentations describe the various functions and data structures
Packit Service 7770af
available to implementers. They are split up over three major components, which
Packit Service 7770af
have all their own source files (plus some common functionality).
Packit Service 7770af
Packit Service 7770af
- [Sass Context](api-context.md) - Trigger and handle the main Sass compilation
Packit Service 7770af
- [Sass Value](api-value.md) - Exchange values and its format with LibSass
Packit Service 7770af
- [Sass Function](api-function.md) - Get invoked by LibSass for function statments
Packit Service 7770af
- [Sass Importer](api-importer.md) - Get invoked by LibSass for @import statments
Packit Service 7770af
Packit Service 7770af
### Basic usage
Packit Service 7770af
Packit Service 7770af
First you will need to include the header file!
Packit Service 7770af
This will automatically load all other headers too!
Packit Service 7770af
Packit Service 7770af
```C
Packit Service 7770af
#include "sass/context.h"
Packit Service 7770af
```
Packit Service 7770af
Packit Service 7770af
## Basic C Example
Packit Service 7770af
Packit Service 7770af
```C
Packit Service 7770af
#include <stdio.h>
Packit Service 7770af
#include "sass/context.h"
Packit Service 7770af
Packit Service 7770af
int main() {
Packit Service 7770af
  puts(libsass_version());
Packit Service 7770af
  return 0;
Packit Service 7770af
}
Packit Service 7770af
```
Packit Service 7770af
Packit Service 7770af
```bash
Packit Service 7770af
gcc -Wall version.c -lsass -o version && ./version
Packit Service 7770af
```
Packit Service 7770af
Packit Service 7770af
## More C Examples
Packit Service 7770af
Packit Service 7770af
- [Sample code for Sass Context](api-context-example.md)
Packit Service 7770af
- [Sample code for Sass Value](api-value-example.md)
Packit Service 7770af
- [Sample code for Sass Function](api-function-example.md)
Packit Service 7770af
- [Sample code for Sass Importer](api-importer-example.md)
Packit Service 7770af
Packit Service 7770af
## Compiling your code
Packit Service 7770af
Packit Service 7770af
The most important is your sass file (or string of sass code). With this, you
Packit Service 7770af
will want to start a LibSass compiler. Here is some pseudocode describing the
Packit Service 7770af
process. The compiler has two different modes: direct input as a string with
Packit Service 7770af
`Sass_Data_Context` or LibSass will do file reading for you by using
Packit Service 7770af
`Sass_File_Context`. See the code for a list of options available
Packit Service 7770af
[Sass_Options](https://github.com/sass/libsass/blob/36feef0/include/sass/interface.h#L18)
Packit Service 7770af
Packit Service 7770af
**Building a file compiler**
Packit Service 7770af
Packit Service 7770af
    context = sass_make_file_context("file.scss")
Packit Service 7770af
    options = sass_file_context_get_options(context)
Packit Service 7770af
    sass_option_set_precision(options, 1)
Packit Service 7770af
    sass_option_set_source_comments(options, true)
Packit Service 7770af
Packit Service 7770af
    sass_file_context_set_options(context, options)
Packit Service 7770af
Packit Service 7770af
    compiler = sass_make_file_compiler(sass_context)
Packit Service 7770af
    sass_compiler_parse(compiler)
Packit Service 7770af
    sass_compiler_execute(compiler)
Packit Service 7770af
Packit Service 7770af
    output = sass_context_get_output_string(context)
Packit Service 7770af
    // Retrieve errors during compilation
Packit Service 7770af
    error_status = sass_context_get_error_status(context)
Packit Service 7770af
    json_error = sass_context_get_error_json(context)
Packit Service 7770af
    // Release memory dedicated to the C compiler
Packit Service 7770af
    sass_delete_compiler(compiler)
Packit Service 7770af
Packit Service 7770af
**Building a data compiler**
Packit Service 7770af
Packit Service 7770af
    context = sass_make_data_context("div { a { color: blue; } }")
Packit Service 7770af
    options = sass_data_context_get_options(context)
Packit Service 7770af
    sass_option_set_precision(options, 1)
Packit Service 7770af
    sass_option_set_source_comments(options, true)
Packit Service 7770af
Packit Service 7770af
    sass_data_context_set_options(context, options)
Packit Service 7770af
Packit Service 7770af
    compiler = sass_make_data_compiler(context)
Packit Service 7770af
    sass_compiler_parse(compiler)
Packit Service 7770af
    sass_compiler_execute(compiler)
Packit Service 7770af
Packit Service 7770af
    output = sass_context_get_output_string(context)
Packit Service 7770af
    // div a { color: blue; }
Packit Service 7770af
    // Retrieve errors during compilation
Packit Service 7770af
    error_status = sass_context_get_error_status(context)
Packit Service 7770af
    json_error = sass_context_get_error_json(context)
Packit Service 7770af
    // Release memory dedicated to the C compiler
Packit Service 7770af
    sass_delete_compiler(compiler)
Packit Service 7770af
Packit Service 7770af
## Sass Context Internals
Packit Service 7770af
Packit Service 7770af
Everything is stored in structs:
Packit Service 7770af
Packit Service 7770af
```C
Packit Service 7770af
struct Sass_Options;
Packit Service 7770af
struct Sass_Context : Sass_Options;
Packit Service 7770af
struct Sass_File_context : Sass_Context;
Packit Service 7770af
struct Sass_Data_context : Sass_Context;
Packit Service 7770af
```
Packit Service 7770af
Packit Service 7770af
This mirrors very well how `libsass` uses these structures.
Packit Service 7770af
Packit Service 7770af
- `Sass_Options` holds everything you feed in before the compilation. It also hosts
Packit Service 7770af
`input_path` and `output_path` options, because they are used to generate/calculate
Packit Service 7770af
relative links in source-maps. The `input_path` is shared with `Sass_File_Context`.
Packit Service 7770af
- `Sass_Context` holds all the data returned by the compilation step.
Packit Service 7770af
- `Sass_File_Context` is a specific implementation that requires no additional fields
Packit Service 7770af
- `Sass_Data_Context` is a specific implementation that adds the `input_source` field
Packit Service 7770af
Packit Service 7770af
Structs can be down-casted to access `context` or `options`!
Packit Service 7770af
Packit Service 7770af
## Memory handling and life-cycles
Packit Service 7770af
Packit Service 7770af
We keep memory around for as long as the main [context](api-context.md) object
Packit Service 7770af
is not destroyed (`sass_delete_context`). LibSass will create copies of most
Packit Service 7770af
inputs/options beside the main sass code. You need to allocate and fill that
Packit Service 7770af
buffer before passing it to LibSass. You may also overtake memory management
Packit Service 7770af
from libsass for certain return values (i.e. `sass_context_take_output_string`).
Packit Service 7770af
Packit Service 7770af
```C
Packit Service 7770af
// to allocate buffer to be filled
Packit Service 7770af
void* sass_alloc_memory(size_t size);
Packit Service 7770af
// to allocate a buffer from existing string
Packit Service 7770af
char* sass_copy_c_string(const char* str);
Packit Service 7770af
// to free overtaken memory when done
Packit Service 7770af
void sass_free_memory(void* ptr);
Packit Service 7770af
```
Packit Service 7770af
Packit Service 7770af
## Miscellaneous API functions
Packit Service 7770af
Packit Service 7770af
```C
Packit Service 7770af
// Some convenient string helper function
Packit Service 7770af
char* sass_string_unquote (const char* str);
Packit Service 7770af
char* sass_string_quote (const char* str, const char quote_mark);
Packit Service 7770af
Packit Service 7770af
// Get compiled libsass version
Packit Service 7770af
const char* libsass_version(void);
Packit Service 7770af
Packit Service 7770af
// Implemented sass language version
Packit Service 7770af
// Hardcoded version 3.4 for time being
Packit Service 7770af
const char* libsass_language_version(void);
Packit Service 7770af
```
Packit Service 7770af
Packit Service 7770af
## Common Pitfalls
Packit Service 7770af
Packit Service 7770af
**input_path**
Packit Service 7770af
Packit Service 7770af
The `input_path` is part of `Sass_Options`, but it also is the main option for
Packit Service 7770af
`Sass_File_Context`. It is also used to generate relative file links in source-
Packit Service 7770af
maps. Therefore it is pretty usefull to pass this information if you have a
Packit Service 7770af
`Sass_Data_Context` and know the original path.
Packit Service 7770af
Packit Service 7770af
**output_path**
Packit Service 7770af
Packit Service 7770af
Be aware that `libsass` does not write the output file itself. This option
Packit Service 7770af
merely exists to give `libsass` the proper information to generate links in
Packit Service 7770af
source-maps. The file has to be written to the disk by the
Packit Service 7770af
binding/implementation. If the `output_path` is omitted, `libsass` tries to
Packit Service 7770af
extrapolate one from the `input_path` by replacing (or adding) the file ending
Packit Service 7770af
with `.css`.
Packit Service 7770af
Packit Service 7770af
## Error Codes
Packit Service 7770af
Packit Service 7770af
The `error_code` is integer value which indicates the type of error that
Packit Service 7770af
occurred inside the LibSass process. Following is the list of error codes along
Packit Service 7770af
with the short description:
Packit Service 7770af
Packit Service 7770af
* 1: normal errors like parsing or `eval` errors
Packit Service 7770af
* 2: bad allocation error (memory error)
Packit Service 7770af
* 3: "untranslated" C++ exception (`throw std::exception`)
Packit Service 7770af
* 4: legacy string exceptions ( `throw const char*` or `std::string` )
Packit Service 7770af
* 5: Some other unknown exception
Packit Service 7770af
Packit Service 7770af
Although for the API consumer, error codes do not offer much value except
Packit Service 7770af
indicating whether *any* error occurred during the compilation, it helps
Packit Service 7770af
debugging the LibSass internal code paths.
Packit Service 7770af
Packit Service 7770af
## Real-World Implementations
Packit Service 7770af
Packit Service 7770af
The proof is in the pudding, so we have highlighted a few implementations that
Packit Service 7770af
should be on par with the latest LibSass interface version. Some of them may not
Packit Service 7770af
have all features implemented!
Packit Service 7770af
Packit Service 7770af
1. [Perl Example](https://github.com/sass/perl-libsass/blob/master/lib/CSS/Sass.xs)
Packit Service 7770af
2. [Go Example](http://godoc.org/github.com/wellington/go-libsass#example-Context-Compile)
Packit Service 7770af
3. [Node Example](https://github.com/sass/node-sass/blob/master/src/binding.cpp)
Packit Service 7770af
Packit Service 7770af
## ABI forward compatibility
Packit Service 7770af
Packit Service 7770af
We use a functional API to make dynamic linking more robust and future
Packit Service 7770af
compatible. The API is not yet 100% stable, so we do not yet guarantee
Packit Service 7770af
[ABI](https://gcc.gnu.org/onlinedocs/libstdc++/manual/abi.html) forward
Packit Service 7770af
compatibility.
Packit Service 7770af
Packit Service 7770af
## Plugins (experimental)
Packit Service 7770af
Packit Service 7770af
LibSass can load plugins from directories. Just define `plugin_path` on context
Packit Service 7770af
options to load all plugins from the directories. To implement plugins, please
Packit Service 7770af
consult the following example implementations.
Packit Service 7770af
Packit Service 7770af
- https://github.com/mgreter/libsass-glob
Packit Service 7770af
- https://github.com/mgreter/libsass-math
Packit Service 7770af
- https://github.com/mgreter/libsass-digest
Packit Service 7770af
Packit Service 7770af
## Internal Structs
Packit Service 7770af
Packit Service 7770af
- [Sass Context Internals](api-context-internal.md)
Packit Service 7770af
- [Sass Value Internals](api-value-internal.md)
Packit Service 7770af
- [Sass Function Internals](api-function-internal.md)
Packit Service 7770af
- [Sass Importer Internals](api-importer-internal.md)